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