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