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