MdeModulePkg/Bus/Pci/NvmExpressDxe/NvmExpress.h

   1 /** @file
   2   NvmExpressDxe driver is used to manage non-volatile memory subsystem which follows
   3   NVM Express specification.
   4
   5   Copyright (c) 2013 - 2016, Intel Corporation. All rights reserved.<BR>
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php.
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _EFI_NVM_EXPRESS_H_
  17 #define _EFI_NVM_EXPRESS_H_
  18
  19 #include <Uefi.h>
  20
  21 #include <IndustryStandard/Pci.h>
  22
  23 #include <Protocol/ComponentName.h>
  24 #include <Protocol/ComponentName2.h>
  25 #include <Protocol/DriverBinding.h>
  26 #include <Protocol/LoadedImage.h>
  27 #include <Protocol/DevicePath.h>
  28 #include <Protocol/PciIo.h>
  29 #include <Protocol/NvmExpressPassthru.h>
  30 #include <Protocol/BlockIo.h>
  31 #include <Protocol/DiskInfo.h>
  32 #include <Protocol/DriverSupportedEfiVersion.h>
  33 #include <Protocol/StorageSecurityCommand.h>
  34
  35 #include <Library/BaseLib.h>
  36 #include <Library/BaseMemoryLib.h>
  37 #include <Library/DebugLib.h>
  38 #include <Library/PrintLib.h>
  39 #include <Library/UefiLib.h>
  40 #include <Library/DevicePathLib.h>
  41 #include <Library/MemoryAllocationLib.h>
  42 #include <Library/UefiBootServicesTableLib.h>
  43 #include <Library/UefiDriverEntryPoint.h>
  44
  45 typedef struct _NVME_CONTROLLER_PRIVATE_DATA NVME_CONTROLLER_PRIVATE_DATA;
  46 typedef struct _NVME_DEVICE_PRIVATE_DATA     NVME_DEVICE_PRIVATE_DATA;
  47
  48 #include "NvmExpressBlockIo.h"
  49 #include "NvmExpressDiskInfo.h"
  50 #include "NvmExpressHci.h"
  51
  52 extern EFI_DRIVER_BINDING_PROTOCOL                gNvmExpressDriverBinding;
  53 extern EFI_COMPONENT_NAME_PROTOCOL                gNvmExpressComponentName;
  54 extern EFI_COMPONENT_NAME2_PROTOCOL               gNvmExpressComponentName2;
  55 extern EFI_DRIVER_SUPPORTED_EFI_VERSION_PROTOCOL  gNvmExpressDriverSupportedEfiVersion;
  56
  57 #define PCI_CLASS_MASS_STORAGE_NVM                0x08  // mass storage sub-class non-volatile memory.
  58 #define PCI_IF_NVMHCI                             0x02  // mass storage programming interface NVMHCI.
  59
  60 #define NVME_ASQ_SIZE                             1     // Number of admin submission queue entries, which is 0-based
  61 #define NVME_ACQ_SIZE                             1     // Number of admin completion queue entries, which is 0-based
  62
  63 #define NVME_CSQ_SIZE                             1     // Number of I/O submission queue entries, which is 0-based
  64 #define NVME_CCQ_SIZE                             1     // Number of I/O completion queue entries, which is 0-based
  65
  66 #define NVME_MAX_QUEUES                           2     // Number of queues supported by the driver
  67
  68 #define NVME_CONTROLLER_ID                        0
  69
  70 //
  71 // Time out value for Nvme transaction execution
  72 //
  73 #define NVME_GENERIC_TIMEOUT                      EFI_TIMER_PERIOD_SECONDS (5)
  74
  75 //
  76 // Unique signature for private data structure.
  77 //
  78 #define NVME_CONTROLLER_PRIVATE_DATA_SIGNATURE    SIGNATURE_32 ('N','V','M','E')
  79
  80 //
  81 // Nvme private data structure.
  82 //
  83 struct _NVME_CONTROLLER_PRIVATE_DATA {
  84   UINT32                              Signature;
  85
  86   EFI_HANDLE                          ControllerHandle;
  87   EFI_HANDLE                          ImageHandle;
  88   EFI_HANDLE                          DriverBindingHandle;
  89
  90   EFI_PCI_IO_PROTOCOL                 *PciIo;
  91   UINT64                              PciAttributes;
  92
  93   EFI_DEVICE_PATH_PROTOCOL            *ParentDevicePath;
  94
  95   EFI_NVM_EXPRESS_PASS_THRU_MODE      PassThruMode;
  96   EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL  Passthru;
  97
  98   //
  99   // pointer to identify controller data
 100   //
 101   NVME_ADMIN_CONTROLLER_DATA          *ControllerData;
 102
 103   //
 104   // 4 x 4kB aligned buffers will be carved out of this buffer.
 105   // 1st 4kB boundary is the start of the admin submission queue.
 106   // 2nd 4kB boundary is the start of the admin completion queue.
 107   // 3rd 4kB boundary is the start of I/O submission queue #1.
 108   // 4th 4kB boundary is the start of I/O completion queue #1.
 109   //
 110   UINT8                               *Buffer;
 111   UINT8                               *BufferPciAddr;
 112
 113   //
 114   // Pointers to 4kB aligned submission & completion queues.
 115   //
 116   NVME_SQ                             *SqBuffer[NVME_MAX_QUEUES];
 117   NVME_CQ                             *CqBuffer[NVME_MAX_QUEUES];
 118   NVME_SQ                             *SqBufferPciAddr[NVME_MAX_QUEUES];
 119   NVME_CQ                             *CqBufferPciAddr[NVME_MAX_QUEUES];
 120
 121   //
 122   // Submission and completion queue indices.
 123   //
 124   NVME_SQTDBL                         SqTdbl[NVME_MAX_QUEUES];
 125   NVME_CQHDBL                         CqHdbl[NVME_MAX_QUEUES];
 126
 127   UINT8                               Pt[NVME_MAX_QUEUES];
 128   UINT16                              Cid[NVME_MAX_QUEUES];
 129
 130   //
 131   // Nvme controller capabilities
 132   //
 133   NVME_CAP                            Cap;
 134
 135   VOID                                *Mapping;
 136 };
 137
 138 #define NVME_CONTROLLER_PRIVATE_DATA_FROM_PASS_THRU(a) \
 139   CR (a, \
 140       NVME_CONTROLLER_PRIVATE_DATA, \
 141       Passthru, \
 142       NVME_CONTROLLER_PRIVATE_DATA_SIGNATURE \
 143       )
 144
 145 //
 146 // Unique signature for private data structure.
 147 //
 148 #define NVME_DEVICE_PRIVATE_DATA_SIGNATURE     SIGNATURE_32 ('X','S','S','D')
 149
 150 //
 151 // Nvme device private data structure
 152 //
 153 struct _NVME_DEVICE_PRIVATE_DATA {
 154   UINT32                                   Signature;
 155
 156   EFI_HANDLE                               DeviceHandle;
 157   EFI_HANDLE                               ControllerHandle;
 158   EFI_HANDLE                               DriverBindingHandle;
 159
 160   EFI_DEVICE_PATH_PROTOCOL                 *DevicePath;
 161
 162   EFI_UNICODE_STRING_TABLE                 *ControllerNameTable;
 163
 164   UINT32                                   NamespaceId;
 165   UINT64                                   NamespaceUuid;
 166
 167   EFI_BLOCK_IO_MEDIA                       Media;
 168   EFI_BLOCK_IO_PROTOCOL                    BlockIo;
 169   EFI_DISK_INFO_PROTOCOL                   DiskInfo;
 170   EFI_STORAGE_SECURITY_COMMAND_PROTOCOL    StorageSecurity;
 171
 172   EFI_LBA                                  NumBlocks;
 173
 174   CHAR16                                   ModelName[80];
 175   NVME_ADMIN_NAMESPACE_DATA                NamespaceData;
 176
 177   NVME_CONTROLLER_PRIVATE_DATA             *Controller;
 178
 179 };
 180
 181 //
 182 // Statments to retrieve the private data from produced protocols.
 183 //
 184 #define NVME_DEVICE_PRIVATE_DATA_FROM_BLOCK_IO(a) \
 185   CR (a, \
 186       NVME_DEVICE_PRIVATE_DATA, \
 187       BlockIo, \
 188       NVME_DEVICE_PRIVATE_DATA_SIGNATURE \
 189       )
 190
 191 #define NVME_DEVICE_PRIVATE_DATA_FROM_DISK_INFO(a) \
 192   CR (a, \
 193       NVME_DEVICE_PRIVATE_DATA, \
 194       DiskInfo, \
 195       NVME_DEVICE_PRIVATE_DATA_SIGNATURE \
 196       )
 197
 198 #define NVME_DEVICE_PRIVATE_DATA_FROM_STORAGE_SECURITY(a)\
 199   CR (a,                                                 \
 200       NVME_DEVICE_PRIVATE_DATA,                          \
 201       StorageSecurity,                                   \
 202       NVME_DEVICE_PRIVATE_DATA_SIGNATURE                 \
 203       )
 204
 205 /**
 206   Retrieves a Unicode string that is the user readable name of the driver.
 207
 208   This function retrieves the user readable name of a driver in the form of a
 209   Unicode string. If the driver specified by This has a user readable name in
 210   the language specified by Language, then a pointer to the driver name is
 211   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 212   by This does not support the language specified by Language,
 213   then EFI_UNSUPPORTED is returned.
 214
 215   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 216                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 217
 218   @param  Language[in]          A pointer to a Null-terminated ASCII string
 219                                 array indicating the language. This is the
 220                                 language of the driver name that the caller is
 221                                 requesting, and it must match one of the
 222                                 languages specified in SupportedLanguages. The
 223                                 number of languages supported by a driver is up
 224                                 to the driver writer. Language is specified
 225                                 in RFC 4646 or ISO 639-2 language code format.
 226
 227   @param  DriverName[out]       A pointer to the Unicode string to return.
 228                                 This Unicode string is the name of the
 229                                 driver specified by This in the language
 230                                 specified by Language.
 231
 232   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 233                                 This and the language specified by Language was
 234                                 returned in DriverName.
 235
 236   @retval EFI_INVALID_PARAMETER Language is NULL.
 237
 238   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 239
 240   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 241                                 the language specified by Language.
 242
 243 **/
 244 EFI_STATUS
 245 EFIAPI
 246 NvmExpressComponentNameGetDriverName (
 247   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 248   IN  CHAR8                        *Language,
 249   OUT CHAR16                       **DriverName
 250   );
 251
 252 /**
 253   Retrieves a Unicode string that is the user readable name of the controller
 254   that is being managed by a driver.
 255
 256   This function retrieves the user readable name of the controller specified by
 257   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 258   driver specified by This has a user readable name in the language specified by
 259   Language, then a pointer to the controller name is returned in ControllerName,
 260   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 261   managing the controller specified by ControllerHandle and ChildHandle,
 262   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 263   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 264
 265   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 266                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 267
 268   @param  ControllerHandle[in]  The handle of a controller that the driver
 269                                 specified by This is managing.  This handle
 270                                 specifies the controller whose name is to be
 271                                 returned.
 272
 273   @param  ChildHandle[in]       The handle of the child controller to retrieve
 274                                 the name of.  This is an optional parameter that
 275                                 may be NULL.  It will be NULL for device
 276                                 drivers.  It will also be NULL for a bus drivers
 277                                 that wish to retrieve the name of the bus
 278                                 controller.  It will not be NULL for a bus
 279                                 driver that wishes to retrieve the name of a
 280                                 child controller.
 281
 282   @param  Language[in]          A pointer to a Null-terminated ASCII string
 283                                 array indicating the language.  This is the
 284                                 language of the driver name that the caller is
 285                                 requesting, and it must match one of the
 286                                 languages specified in SupportedLanguages. The
 287                                 number of languages supported by a driver is up
 288                                 to the driver writer. Language is specified in
 289                                 RFC 4646 or ISO 639-2 language code format.
 290
 291   @param  ControllerName[out]   A pointer to the Unicode string to return.
 292                                 This Unicode string is the name of the
 293                                 controller specified by ControllerHandle and
 294                                 ChildHandle in the language specified by
 295                                 Language from the point of view of the driver
 296                                 specified by This.
 297
 298   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 299                                 the language specified by Language for the
 300                                 driver specified by This was returned in
 301                                 DriverName.
 302
 303   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 304
 305   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 306                                 EFI_HANDLE.
 307
 308   @retval EFI_INVALID_PARAMETER Language is NULL.
 309
 310   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 311
 312   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 313                                 managing the controller specified by
 314                                 ControllerHandle and ChildHandle.
 315
 316   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 317                                 the language specified by Language.
 318
 319 **/
 320 EFI_STATUS
 321 EFIAPI
 322 NvmExpressComponentNameGetControllerName (
 323   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 324   IN  EFI_HANDLE                                      ControllerHandle,
 325   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 326   IN  CHAR8                                           *Language,
 327   OUT CHAR16                                          **ControllerName
 328   );
 329
 330 /**
 331   Tests to see if this driver supports a given controller. If a child device is provided,
 332   it further tests to see if this driver supports creating a handle for the specified child device.
 333
 334   This function checks to see if the driver specified by This supports the device specified by
 335   ControllerHandle. Drivers will typically use the device path attached to
 336   ControllerHandle and/or the services from the bus I/O abstraction attached to
 337   ControllerHandle to determine if the driver supports ControllerHandle. This function
 338   may be called many times during platform initialization. In order to reduce boot times, the tests
 339   performed by this function must be very small, and take as little time as possible to execute. This
 340   function must not change the state of any hardware devices, and this function must be aware that the
 341   device specified by ControllerHandle may already be managed by the same driver or a
 342   different driver. This function must match its calls to AllocatePages() with FreePages(),
 343   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 344   Since ControllerHandle may have been previously started by the same driver, if a protocol is
 345   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 346   to guarantee the state of ControllerHandle is not modified by this function.
 347
 348   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 349   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 350                                    must support a protocol interface that supplies
 351                                    an I/O abstraction to the driver.
 352   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 353                                    parameter is ignored by device drivers, and is optional for bus
 354                                    drivers. For bus drivers, if this parameter is not NULL, then
 355                                    the bus driver must determine if the bus controller specified
 356                                    by ControllerHandle and the child controller specified
 357                                    by RemainingDevicePath are both supported by this
 358                                    bus driver.
 359
 360   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 361                                    RemainingDevicePath is supported by the driver specified by This.
 362   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 363                                    RemainingDevicePath is already being managed by the driver
 364                                    specified by This.
 365   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 366                                    RemainingDevicePath is already being managed by a different
 367                                    driver or an application that requires exclusive access.
 368                                    Currently not implemented.
 369   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 370                                    RemainingDevicePath is not supported by the driver specified by This.
 371 **/
 372 EFI_STATUS
 373 EFIAPI
 374 NvmExpressDriverBindingSupported (
 375   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 376   IN EFI_HANDLE                   Controller,
 377   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 378   );
 379
 380 /**
 381   Starts a device controller or a bus controller.
 382
 383   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 384   As a result, much of the error checking on the parameters to Start() has been moved into this
 385   common boot service. It is legal to call Start() from other locations,
 386   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 387   1. ControllerHandle must be a valid EFI_HANDLE.
 388   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 389      EFI_DEVICE_PATH_PROTOCOL.
 390   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 391      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 392
 393   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 394   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 395                                    must support a protocol interface that supplies
 396                                    an I/O abstraction to the driver.
 397   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 398                                    parameter is ignored by device drivers, and is optional for bus
 399                                    drivers. For a bus driver, if this parameter is NULL, then handles
 400                                    for all the children of Controller are created by this driver.
 401                                    If this parameter is not NULL and the first Device Path Node is
 402                                    not the End of Device Path Node, then only the handle for the
 403                                    child device specified by the first Device Path Node of
 404                                    RemainingDevicePath is created by this driver.
 405                                    If the first Device Path Node of RemainingDevicePath is
 406                                    the End of Device Path Node, no child handle is created by this
 407                                    driver.
 408
 409   @retval EFI_SUCCESS              The device was started.
 410   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 411   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 412   @retval Others                   The driver failded to start the device.
 413
 414 **/
 415 EFI_STATUS
 416 EFIAPI
 417 NvmExpressDriverBindingStart (
 418   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 419   IN EFI_HANDLE                   Controller,
 420   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 421   );
 422
 423 /**
 424   Stops a device controller or a bus controller.
 425
 426   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 427   As a result, much of the error checking on the parameters to Stop() has been moved
 428   into this common boot service. It is legal to call Stop() from other locations,
 429   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 430   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 431      same driver's Start() function.
 432   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 433      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 434      Start() function, and the Start() function must have called OpenProtocol() on
 435      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 436
 437   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 438   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 439                                 support a bus specific I/O protocol for the driver
 440                                 to use to stop the device.
 441   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 442   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 443                                 if NumberOfChildren is 0.
 444
 445   @retval EFI_SUCCESS           The device was stopped.
 446   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 447
 448 **/
 449 EFI_STATUS
 450 EFIAPI
 451 NvmExpressDriverBindingStop (
 452   IN  EFI_DRIVER_BINDING_PROTOCOL     *This,
 453   IN  EFI_HANDLE                      Controller,
 454   IN  UINTN                           NumberOfChildren,
 455   IN  EFI_HANDLE                      *ChildHandleBuffer
 456   );
 457
 458 /**
 459   Sends an NVM Express Command Packet to an NVM Express controller or namespace. This function supports
 460   both blocking I/O and nonblocking I/O. The blocking I/O functionality is required, and the nonblocking
 461   I/O functionality is optional.
 462
 463   @param[in]     This                A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance.
 464   @param[in]     NamespaceId         Is a 32 bit Namespace ID to which the Express HCI command packet will be sent.
 465                                      A value of 0 denotes the NVM Express controller, a value of all 0FFh in the namespace
 466                                      ID specifies that the command packet should be sent to all valid namespaces.
 467   @param[in,out] Packet              A pointer to the NVM Express HCI Command Packet to send to the NVMe namespace specified
 468                                      by NamespaceId.
 469   @param[in]     Event               If nonblocking I/O is not supported then Event is ignored, and blocking I/O is performed.
 470                                      If Event is NULL, then blocking I/O is performed. If Event is not NULL and non blocking I/O
 471                                      is supported, then nonblocking I/O is performed, and Event will be signaled when the NVM
 472                                      Express Command Packet completes.
 473
 474   @retval EFI_SUCCESS                The NVM Express Command Packet was sent by the host. TransferLength bytes were transferred
 475                                      to, or from DataBuffer.
 476   @retval EFI_BAD_BUFFER_SIZE        The NVM Express Command Packet was not executed. The number of bytes that could be transferred
 477                                      is returned in TransferLength.
 478   @retval EFI_NOT_READY              The NVM Express Command Packet could not be sent because the controller is not ready. The caller
 479                                      may retry again later.
 480   @retval EFI_DEVICE_ERROR           A device error occurred while attempting to send the NVM Express Command Packet.
 481   @retval EFI_INVALID_PARAMETER      Namespace, or the contents of EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET are invalid. The NVM
 482                                      Express Command Packet was not sent, so no additional status information is available.
 483   @retval EFI_UNSUPPORTED            The command described by the NVM Express Command Packet is not supported by the host adapter.
 484                                      The NVM Express Command Packet was not sent, so no additional status information is available.
 485   @retval EFI_TIMEOUT                A timeout occurred while waiting for the NVM Express Command Packet to execute.
 486
 487 **/
 488 EFI_STATUS
 489 EFIAPI
 490 NvmExpressPassThru (
 491   IN     EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL          *This,
 492   IN     UINT32                                      NamespaceId,
 493   IN OUT EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET    *Packet,
 494   IN     EFI_EVENT                                   Event OPTIONAL
 495   );
 496
 497 /**
 498   Used to retrieve the next namespace ID for this NVM Express controller.
 499
 500   The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.GetNextNamespace() function retrieves the next valid
 501   namespace ID on this NVM Express controller.
 502
 503   If on input the value pointed to by NamespaceId is 0xFFFFFFFF, then the first valid namespace
 504   ID defined on the NVM Express controller is returned in the location pointed to by NamespaceId
 505   and a status of EFI_SUCCESS is returned.
 506
 507   If on input the value pointed to by NamespaceId is an invalid namespace ID other than 0xFFFFFFFF,
 508   then EFI_INVALID_PARAMETER is returned.
 509
 510   If on input the value pointed to by NamespaceId is a valid namespace ID, then the next valid
 511   namespace ID on the NVM Express controller is returned in the location pointed to by NamespaceId,
 512   and EFI_SUCCESS is returned.
 513
 514   If the value pointed to by NamespaceId is the namespace ID of the last namespace on the NVM
 515   Express controller, then EFI_NOT_FOUND is returned.
 516
 517   @param[in]     This           A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance.
 518   @param[in,out] NamespaceId    On input, a pointer to a legal NamespaceId for an NVM Express
 519                                 namespace present on the NVM Express controller. On output, a
 520                                 pointer to the next NamespaceId of an NVM Express namespace on
 521                                 an NVM Express controller. An input value of 0xFFFFFFFF retrieves
 522                                 the first NamespaceId for an NVM Express namespace present on an
 523                                 NVM Express controller.
 524
 525   @retval EFI_SUCCESS           The Namespace ID of the next Namespace was returned.
 526   @retval EFI_NOT_FOUND         There are no more namespaces defined on this controller.
 527   @retval EFI_INVALID_PARAMETER NamespaceId is an invalid value other than 0xFFFFFFFF.
 528
 529 **/
 530 EFI_STATUS
 531 EFIAPI
 532 NvmExpressGetNextNamespace (
 533   IN     EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL          *This,
 534   IN OUT UINT32                                      *NamespaceId
 535   );
 536
 537 /**
 538   Used to translate a device path node to a namespace ID.
 539
 540   The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.GetNamespace() function determines the namespace ID associated with the
 541   namespace described by DevicePath.
 542
 543   If DevicePath is a device path node type that the NVM Express Pass Thru driver supports, then the NVM Express
 544   Pass Thru driver will attempt to translate the contents DevicePath into a namespace ID.
 545
 546   If this translation is successful, then that namespace ID is returned in NamespaceId, and EFI_SUCCESS is returned
 547
 548   @param[in]  This                A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance.
 549   @param[in]  DevicePath          A pointer to the device path node that describes an NVM Express namespace on
 550                                   the NVM Express controller.
 551   @param[out] NamespaceId         The NVM Express namespace ID contained in the device path node.
 552
 553   @retval EFI_SUCCESS             DevicePath was successfully translated to NamespaceId.
 554   @retval EFI_INVALID_PARAMETER   If DevicePath or NamespaceId are NULL, then EFI_INVALID_PARAMETER is returned.
 555   @retval EFI_UNSUPPORTED         If DevicePath is not a device path node type that the NVM Express Pass Thru driver
 556                                   supports, then EFI_UNSUPPORTED is returned.
 557   @retval EFI_NOT_FOUND           If DevicePath is a device path node type that the NVM Express Pass Thru driver
 558                                   supports, but there is not a valid translation from DevicePath to a namespace ID,
 559                                   then EFI_NOT_FOUND is returned.
 560 **/
 561 EFI_STATUS
 562 EFIAPI
 563 NvmExpressGetNamespace (
 564   IN     EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL          *This,
 565   IN     EFI_DEVICE_PATH_PROTOCOL                    *DevicePath,
 566      OUT UINT32                                      *NamespaceId
 567   );
 568
 569 /**
 570   Used to allocate and build a device path node for an NVM Express namespace on an NVM Express controller.
 571
 572   The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.BuildDevicePath() function allocates and builds a single device
 573   path node for the NVM Express namespace specified by NamespaceId.
 574
 575   If the NamespaceId is not valid, then EFI_NOT_FOUND is returned.
 576
 577   If DevicePath is NULL, then EFI_INVALID_PARAMETER is returned.
 578
 579   If there are not enough resources to allocate the device path node, then EFI_OUT_OF_RESOURCES is returned.
 580
 581   Otherwise, DevicePath is allocated with the boot service AllocatePool(), the contents of DevicePath are
 582   initialized to describe the NVM Express namespace specified by NamespaceId, and EFI_SUCCESS is returned.
 583
 584   @param[in]     This                A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance.
 585   @param[in]     NamespaceId         The NVM Express namespace ID  for which a device path node is to be
 586                                      allocated and built. Caller must set the NamespaceId to zero if the
 587                                      device path node will contain a valid UUID.
 588   @param[in,out] DevicePath          A pointer to a single device path node that describes the NVM Express
 589                                      namespace specified by NamespaceId. This function is responsible for
 590                                      allocating the buffer DevicePath with the boot service AllocatePool().
 591                                      It is the caller's responsibility to free DevicePath when the caller
 592                                      is finished with DevicePath.
 593   @retval EFI_SUCCESS                The device path node that describes the NVM Express namespace specified
 594                                      by NamespaceId was allocated and returned in DevicePath.
 595   @retval EFI_NOT_FOUND              The NamespaceId is not valid.
 596   @retval EFI_INVALID_PARAMETER      DevicePath is NULL.
 597   @retval EFI_OUT_OF_RESOURCES       There are not enough resources to allocate the DevicePath node.
 598
 599 **/
 600 EFI_STATUS
 601 EFIAPI
 602 NvmExpressBuildDevicePath (
 603   IN     EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL          *This,
 604   IN     UINT32                                      NamespaceId,
 605   IN OUT EFI_DEVICE_PATH_PROTOCOL                    **DevicePath
 606   );
 607
 608 #endif