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