[mirror_edk2.git] / MdeModulePkg / Bus / Pci / NvmExpressPei / NvmExpressPei.h

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