MdeModulePkg/Bus/Pci/NvmExpressPei/NvmExpressPei.h

   1 /** @file
   2   The NvmExpressPei driver is used to manage non-volatile memory subsystem
   3   which follows NVM Express specification at PEI phase.
   4
   5   Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef _NVM_EXPRESS_PEI_H_
  12 #define _NVM_EXPRESS_PEI_H_
  13
  14 #include <PiPei.h>
  15
  16 #include <IndustryStandard/Nvme.h>
  17
  18 #include <Ppi/NvmExpressHostController.h>
  19 #include <Ppi/BlockIo.h>
  20 #include <Ppi/BlockIo2.h>
  21 #include <Ppi/StorageSecurityCommand.h>
  22 #include <Ppi/NvmExpressPassThru.h>
  23 #include <Ppi/IoMmu.h>
  24 #include <Ppi/EndOfPeiPhase.h>
  25
  26 #include <Library/DebugLib.h>
  27 #include <Library/PeiServicesLib.h>
  28 #include <Library/MemoryAllocationLib.h>
  29 #include <Library/BaseMemoryLib.h>
  30 #include <Library/IoLib.h>
  31 #include <Library/TimerLib.h>
  32
  33 //
  34 // Structure forward declarations
  35 //
  36 typedef struct _PEI_NVME_NAMESPACE_INFO           PEI_NVME_NAMESPACE_INFO;
  37 typedef struct _PEI_NVME_CONTROLLER_PRIVATE_DATA  PEI_NVME_CONTROLLER_PRIVATE_DATA;
  38
  39 #include "NvmExpressPeiHci.h"
  40 #include "NvmExpressPeiPassThru.h"
  41 #include "NvmExpressPeiBlockIo.h"
  42 #include "NvmExpressPeiStorageSecurity.h"
  43
  44 //
  45 // NVME PEI driver implementation related definitions
  46 //
  47 #define NVME_MAX_QUEUES                               2     // Number of I/O queues supported by the driver, 1 for AQ, 1 for CQ
  48 #define NVME_ASQ_SIZE                                 1     // Number of admin submission queue entries, which is 0-based
  49 #define NVME_ACQ_SIZE                                 1     // Number of admin completion queue entries, which is 0-based
  50 #define NVME_CSQ_SIZE                                 63    // Number of I/O submission queue entries, which is 0-based
  51 #define NVME_CCQ_SIZE                                 63    // Number of I/O completion queue entries, which is 0-based
  52 #define NVME_PRP_SIZE                                 (8)   // Pages of PRP list
  53
  54 #define NVME_MEM_MAX_PAGES                                           \
  55   (                                                                  \
  56   1                                         /* ASQ */             +  \
  57   1                                         /* ACQ */             +  \
  58   1                                         /* SQs */             +  \
  59   1                                         /* CQs */             +  \
  60   NVME_PRP_SIZE)                            /* PRPs */
  61
  62 #define NVME_ADMIN_QUEUE                              0x00
  63 #define NVME_IO_QUEUE                                 0x01
  64 #define NVME_GENERIC_TIMEOUT                          5000000   // Generic PassThru command timeout value, in us unit
  65 #define NVME_POLL_INTERVAL                            100       // Poll interval for PassThru command, in us unit
  66
  67 //
  68 // Nvme namespace data structure.
  69 //
  70 struct _PEI_NVME_NAMESPACE_INFO {
  71   UINT32                                    NamespaceId;
  72   UINT64                                    NamespaceUuid;
  73   EFI_PEI_BLOCK_IO2_MEDIA                   Media;
  74
  75   PEI_NVME_CONTROLLER_PRIVATE_DATA          *Controller;
  76 };
  77
  78 #define NVME_CONTROLLER_NSID        0
  79
  80 //
  81 // Unique signature for private data structure.
  82 //
  83 #define NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE    SIGNATURE_32 ('N','V','P','C')
  84
  85 //
  86 // Nvme controller private data structure.
  87 //
  88 struct _PEI_NVME_CONTROLLER_PRIVATE_DATA {
  89   UINT32                                    Signature;
  90   UINTN                                     MmioBase;
  91   EFI_NVM_EXPRESS_PASS_THRU_MODE            PassThruMode;
  92   UINTN                                     DevicePathLength;
  93   EFI_DEVICE_PATH_PROTOCOL                  *DevicePath;
  94
  95   EFI_PEI_RECOVERY_BLOCK_IO_PPI             BlkIoPpi;
  96   EFI_PEI_RECOVERY_BLOCK_IO2_PPI            BlkIo2Ppi;
  97   EDKII_PEI_STORAGE_SECURITY_CMD_PPI        StorageSecurityPpi;
  98   EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI       NvmePassThruPpi;
  99   EFI_PEI_PPI_DESCRIPTOR                    BlkIoPpiList;
 100   EFI_PEI_PPI_DESCRIPTOR                    BlkIo2PpiList;
 101   EFI_PEI_PPI_DESCRIPTOR                    StorageSecurityPpiList;
 102   EFI_PEI_PPI_DESCRIPTOR                    NvmePassThruPpiList;
 103   EFI_PEI_NOTIFY_DESCRIPTOR                 EndOfPeiNotifyList;
 104
 105   //
 106   // Pointer to identify controller data
 107   //
 108   NVME_ADMIN_CONTROLLER_DATA                *ControllerData;
 109
 110   //
 111   // (4 + NVME_PRP_SIZE) x 4kB aligned buffers will be carved out of this buffer
 112   // 1st 4kB boundary is the start of the admin submission queue
 113   // 2nd 4kB boundary is the start of the admin completion queue
 114   // 3rd 4kB boundary is the start of I/O submission queue
 115   // 4th 4kB boundary is the start of I/O completion queue
 116   // 5th 4kB boundary is the start of PRP list buffers
 117   //
 118   VOID                                      *Buffer;
 119   VOID                                      *BufferMapping;
 120
 121   //
 122   // Pointers to 4kB aligned submission & completion queues
 123   //
 124   NVME_SQ                                   *SqBuffer[NVME_MAX_QUEUES];
 125   NVME_CQ                                   *CqBuffer[NVME_MAX_QUEUES];
 126
 127   //
 128   // Submission and completion queue indices
 129   //
 130   NVME_SQTDBL                               SqTdbl[NVME_MAX_QUEUES];
 131   NVME_CQHDBL                               CqHdbl[NVME_MAX_QUEUES];
 132
 133   UINT8                                     Pt[NVME_MAX_QUEUES];
 134   UINT16                                    Cid[NVME_MAX_QUEUES];
 135
 136   //
 137   // Nvme controller capabilities
 138   //
 139   NVME_CAP                                  Cap;
 140
 141   //
 142   // Namespaces information on the controller
 143   //
 144   UINT32                                    ActiveNamespaceNum;
 145   PEI_NVME_NAMESPACE_INFO                   *NamespaceInfo;
 146 };
 147
 148 #define GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO(a)               \
 149   CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, BlkIoPpi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)
 150 #define GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO2(a)              \
 151   CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, BlkIo2Ppi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)
 152 #define GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_STROAGE_SECURITY(a)    \
 153   CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, StorageSecurityPpi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)
 154 #define GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_NVME_PASSTHRU(a)       \
 155   CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, NvmePassThruPpi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)
 156 #define GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_NOTIFY(a)              \
 157   CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, EndOfPeiNotifyList, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)
 158
 159
 160 //
 161 // Internal functions
 162 //
 163
 164 /**
 165   Allocates pages that are suitable for an OperationBusMasterCommonBuffer or
 166   OperationBusMasterCommonBuffer64 mapping.
 167
 168   @param  Pages                 The number of pages to allocate.
 169   @param  HostAddress           A pointer to store the base system memory address of the
 170                                 allocated range.
 171   @param  DeviceAddress         The resulting map address for the bus master PCI controller to use to
 172                                 access the hosts HostAddress.
 173   @param  Mapping               A resulting value to pass to Unmap().
 174
 175   @retval EFI_SUCCESS           The requested memory pages were allocated.
 176   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 177                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
 178   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 179   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 180
 181 **/
 182 EFI_STATUS
 183 IoMmuAllocateBuffer (
 184   IN UINTN                  Pages,
 185   OUT VOID                  **HostAddress,
 186   OUT EFI_PHYSICAL_ADDRESS  *DeviceAddress,
 187   OUT VOID                  **Mapping
 188   );
 189
 190 /**
 191   Frees memory that was allocated with AllocateBuffer().
 192
 193   @param  Pages                 The number of pages to free.
 194   @param  HostAddress           The base system memory address of the allocated range.
 195   @param  Mapping               The mapping value returned from Map().
 196
 197   @retval EFI_SUCCESS           The requested memory pages were freed.
 198   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
 199                                 was not allocated with AllocateBuffer().
 200
 201 **/
 202 EFI_STATUS
 203 IoMmuFreeBuffer (
 204   IN UINTN                  Pages,
 205   IN VOID                   *HostAddress,
 206   IN VOID                   *Mapping
 207   );
 208
 209 /**
 210   Provides the controller-specific addresses required to access system memory from a
 211   DMA bus master.
 212
 213   @param  Operation             Indicates if the bus master is going to read or write to system memory.
 214   @param  HostAddress           The system memory address to map to the PCI controller.
 215   @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes
 216                                 that were mapped.
 217   @param  DeviceAddress         The resulting map address for the bus master PCI controller to use to
 218                                 access the hosts HostAddress.
 219   @param  Mapping               A resulting value to pass to Unmap().
 220
 221   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
 222   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
 223   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 224   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 225   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
 226
 227 **/
 228 EFI_STATUS
 229 IoMmuMap (
 230   IN  EDKII_IOMMU_OPERATION Operation,
 231   IN VOID                   *HostAddress,
 232   IN  OUT UINTN             *NumberOfBytes,
 233   OUT EFI_PHYSICAL_ADDRESS  *DeviceAddress,
 234   OUT VOID                  **Mapping
 235   );
 236
 237 /**
 238   Completes the Map() operation and releases any corresponding resources.
 239
 240   @param  Mapping               The mapping value returned from Map().
 241
 242   @retval EFI_SUCCESS           The range was unmapped.
 243   @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
 244   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
 245 **/
 246 EFI_STATUS
 247 IoMmuUnmap (
 248   IN VOID                  *Mapping
 249   );
 250
 251 /**
 252   One notified function to cleanup the allocated resources at the end of PEI.
 253
 254   @param[in] PeiServices         Pointer to PEI Services Table.
 255   @param[in] NotifyDescriptor    Pointer to the descriptor for the Notification
 256                                  event that caused this function to execute.
 257   @param[in] Ppi                 Pointer to the PPI data associated with this function.
 258
 259   @retval     EFI_SUCCESS  The function completes successfully
 260
 261 **/
 262 EFI_STATUS
 263 EFIAPI
 264 NvmePeimEndOfPei (
 265   IN EFI_PEI_SERVICES           **PeiServices,
 266   IN EFI_PEI_NOTIFY_DESCRIPTOR  *NotifyDescriptor,
 267   IN VOID                       *Ppi
 268   );
 269
 270 /**
 271   Get the size of the current device path instance.
 272
 273   @param[in]  DevicePath             A pointer to the EFI_DEVICE_PATH_PROTOCOL
 274                                      structure.
 275   @param[out] InstanceSize           The size of the current device path instance.
 276   @param[out] EntireDevicePathEnd    Indicate whether the instance is the last
 277                                      one in the device path strucure.
 278
 279   @retval EFI_SUCCESS    The size of the current device path instance is fetched.
 280   @retval Others         Fails to get the size of the current device path instance.
 281
 282 **/
 283 EFI_STATUS
 284 GetDevicePathInstanceSize (
 285   IN  EFI_DEVICE_PATH_PROTOCOL    *DevicePath,
 286   OUT UINTN                       *InstanceSize,
 287   OUT BOOLEAN                     *EntireDevicePathEnd
 288   );
 289
 290 /**
 291   Check the validity of the device path of a NVM Express host controller.
 292
 293   @param[in] DevicePath          A pointer to the EFI_DEVICE_PATH_PROTOCOL
 294                                  structure.
 295   @param[in] DevicePathLength    The length of the device path.
 296
 297   @retval EFI_SUCCESS              The device path is valid.
 298   @retval EFI_INVALID_PARAMETER    The device path is invalid.
 299
 300 **/
 301 EFI_STATUS
 302 NvmeIsHcDevicePathValid (
 303   IN EFI_DEVICE_PATH_PROTOCOL    *DevicePath,
 304   IN UINTN                       DevicePathLength
 305   );
 306
 307 /**
 308   Build the device path for an Nvm Express device with given namespace identifier
 309   and namespace extended unique identifier.
 310
 311   @param[in]  Private              A pointer to the PEI_NVME_CONTROLLER_PRIVATE_DATA
 312                                    data structure.
 313   @param[in]  NamespaceId          The given namespace identifier.
 314   @param[in]  NamespaceUuid        The given namespace extended unique identifier.
 315   @param[out] DevicePathLength     The length of the device path in bytes specified
 316                                    by DevicePath.
 317   @param[out] DevicePath           The device path of Nvm Express device.
 318
 319   @retval EFI_SUCCESS              The operation succeeds.
 320   @retval EFI_INVALID_PARAMETER    The parameters are invalid.
 321   @retval EFI_OUT_OF_RESOURCES     The operation fails due to lack of resources.
 322
 323 **/
 324 EFI_STATUS
 325 NvmeBuildDevicePath (
 326   IN  PEI_NVME_CONTROLLER_PRIVATE_DATA    *Private,
 327   IN  UINT32                              NamespaceId,
 328   IN  UINT64                              NamespaceUuid,
 329   OUT UINTN                               *DevicePathLength,
 330   OUT EFI_DEVICE_PATH_PROTOCOL            **DevicePath
 331   );
 332
 333 /**
 334   Determine if a specific NVM Express controller can be skipped for S3 phase.
 335
 336   @param[in]  HcDevicePath          Device path of the controller.
 337   @param[in]  HcDevicePathLength    Length of the device path specified by
 338                                     HcDevicePath.
 339
 340   @retval    The number of ports that need to be enumerated.
 341
 342 **/
 343 BOOLEAN
 344 NvmeS3SkipThisController (
 345   IN  EFI_DEVICE_PATH_PROTOCOL    *HcDevicePath,
 346   IN  UINTN                       HcDevicePathLength
 347   );
 348
 349 #endif