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