#include <PiPei.h>
#include <IndustryStandard/Nvme.h>
#include <IndustryStandard/Pci.h>
#include <Ppi/NvmExpressHostController.h>
#include <Ppi/BlockIo.h>
#include <Ppi/BlockIo2.h>
#include <Ppi/StorageSecurityCommand.h>
#include <Ppi/NvmExpressPassThru.h>
#include <Ppi/IoMmu.h>
#include <Ppi/EndOfPeiPhase.h>
#include <Ppi/PciDevice.h>
#include <Library/DebugLib.h>
#include <Library/PeiServicesLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/IoLib.h>
#include <Library/TimerLib.h>
#include <Library/DevicePathLib.h>
#include "NvmExpressPeiHci.h"
#include "NvmExpressPeiPassThru.h"
#include "NvmExpressPeiBlockIo.h"
#include "NvmExpressPeiStorageSecurity.h"

Data Structures
struct	_PEI_NVME_NAMESPACE_INFO

struct	_PEI_NVME_CONTROLLER_PRIVATE_DATA

Macros
#define	IS_PCI_NVMHCI(_p) IS_CLASS3 (_p, PCI_CLASS_MASS_STORAGE, PCI_CLASS_MASS_STORAGE_SOLID_STATE, PCI_IF_MASS_STORAGE_SOLID_STATE_ENTERPRISE_NVMHCI)

#define	NVME_MAX_QUEUES 2

#define	NVME_ASQ_SIZE 1

#define	NVME_ACQ_SIZE 1

#define	NVME_CSQ_SIZE 63

#define	NVME_CCQ_SIZE 63

#define	NVME_PRP_SIZE (8)

#define	NVME_MEM_MAX_PAGES

#define	NVME_ADMIN_QUEUE 0x00

#define	NVME_IO_QUEUE 0x01

#define	NVME_GENERIC_TIMEOUT 5000000

#define	NVME_POLL_INTERVAL 100

#define	NVME_CONTROLLER_NSID 0

#define	NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('N','V','P','C')

#define	GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO(a) CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, BlkIoPpi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)

#define	GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO2(a) CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, BlkIo2Ppi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)

#define	GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_STROAGE_SECURITY(a) CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, StorageSecurityPpi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)

#define	GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_NVME_PASSTHRU(a) CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, NvmePassThruPpi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)

#define	GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_NOTIFY(a) CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, EndOfPeiNotifyList, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)

Typedefs
typedef struct _PEI_NVME_NAMESPACE_INFO	PEI_NVME_NAMESPACE_INFO

typedef struct _PEI_NVME_CONTROLLER_PRIVATE_DATA	PEI_NVME_CONTROLLER_PRIVATE_DATA

Functions
EFI_STATUS	IoMmuAllocateBuffer (IN UINTN Pages, OUT VOID *HostAddress, OUT EFI_PHYSICAL_ADDRESS DeviceAddress, OUT VOID **Mapping)

EFI_STATUS	IoMmuFreeBuffer (IN UINTN Pages, IN VOID HostAddress, IN VOID Mapping)

EFI_STATUS	IoMmuMap (IN EDKII_IOMMU_OPERATION Operation, IN VOID HostAddress, IN OUT UINTN NumberOfBytes, OUT EFI_PHYSICAL_ADDRESS DeviceAddress, OUT VOID *Mapping)

EFI_STATUS	IoMmuUnmap (IN VOID *Mapping)

EFI_STATUS EFIAPI	NvmePeimEndOfPei (IN EFI_PEI_SERVICES *PeiServices, IN EFI_PEI_NOTIFY_DESCRIPTOR NotifyDescriptor, IN VOID *Ppi)

EFI_STATUS	GetDevicePathInstanceSize (IN EFI_DEVICE_PATH_PROTOCOL DevicePath, OUT UINTN InstanceSize, OUT BOOLEAN *EntireDevicePathEnd)

EFI_STATUS	NvmeIsHcDevicePathValid (IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, IN UINTN DevicePathLength)

EFI_STATUS	NvmeBuildDevicePath (IN PEI_NVME_CONTROLLER_PRIVATE_DATA Private, IN UINT32 NamespaceId, IN UINT64 NamespaceUuid, OUT UINTN DevicePathLength, OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath)

BOOLEAN	NvmeS3SkipThisController (IN EFI_DEVICE_PATH_PROTOCOL *HcDevicePath, IN UINTN HcDevicePathLength)

EFI_STATUS EFIAPI	NvmePciDevicePpiInstallationCallback (IN EFI_PEI_SERVICES *PeiServices, IN EFI_PEI_NOTIFY_DESCRIPTOR NotifyDescriptor, IN VOID *Ppi)

EFI_STATUS EFIAPI	NvmeHostControllerPpiInstallationCallback (IN EFI_PEI_SERVICES *PeiServices, IN EFI_PEI_NOTIFY_DESCRIPTOR NotifyDescriptor, IN VOID *Ppi)

Detailed Description

The NvmExpressPei driver is used to manage non-volatile memory subsystem which follows NVM Express specification at PEI phase.

SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file NvmExpressPei.h.

Macro Definition Documentation

◆ GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO

#define GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO ( a ) CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, BlkIoPpi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)

Definition at line 162 of file NvmExpressPei.h.

◆ GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO2

#define GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO2 ( a ) CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, BlkIo2Ppi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)

Definition at line 164 of file NvmExpressPei.h.

◆ GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_NOTIFY

#define GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_NOTIFY ( a ) CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, EndOfPeiNotifyList, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)

Definition at line 170 of file NvmExpressPei.h.

◆ GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_NVME_PASSTHRU

#define GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_NVME_PASSTHRU ( a ) CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, NvmePassThruPpi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)

Definition at line 168 of file NvmExpressPei.h.

◆ GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_STROAGE_SECURITY

#define GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_STROAGE_SECURITY ( a ) CR (a, PEI_NVME_CONTROLLER_PRIVATE_DATA, StorageSecurityPpi, NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)

Definition at line 166 of file NvmExpressPei.h.

◆ IS_PCI_NVMHCI

#define IS_PCI_NVMHCI ( _p ) IS_CLASS3 (_p, PCI_CLASS_MASS_STORAGE, PCI_CLASS_MASS_STORAGE_SOLID_STATE, PCI_IF_MASS_STORAGE_SOLID_STATE_ENTERPRISE_NVMHCI)

Macro that checks whether device is a NVMHCI Interface.

Parameters

_p	Specified device.

Return values

TRUE	Device is a NVMHCI Interface.
FALSE	Device is not a NVMHCI Interface.

Definition at line 51 of file NvmExpressPei.h.

◆ NVME_ACQ_SIZE

#define NVME_ACQ_SIZE 1

Definition at line 63 of file NvmExpressPei.h.

◆ NVME_ADMIN_QUEUE

#define NVME_ADMIN_QUEUE 0x00

Definition at line 76 of file NvmExpressPei.h.

◆ NVME_ASQ_SIZE

#define NVME_ASQ_SIZE 1

Definition at line 62 of file NvmExpressPei.h.

◆ NVME_CCQ_SIZE

#define NVME_CCQ_SIZE 63

Definition at line 65 of file NvmExpressPei.h.

◆ NVME_CONTROLLER_NSID

#define NVME_CONTROLLER_NSID 0

Definition at line 92 of file NvmExpressPei.h.

◆ NVME_CSQ_SIZE

#define NVME_CSQ_SIZE 63

Definition at line 64 of file NvmExpressPei.h.

◆ NVME_GENERIC_TIMEOUT

#define NVME_GENERIC_TIMEOUT 5000000

Definition at line 78 of file NvmExpressPei.h.

◆ NVME_IO_QUEUE

#define NVME_IO_QUEUE 0x01

Definition at line 77 of file NvmExpressPei.h.

◆ NVME_MAX_QUEUES

#define NVME_MAX_QUEUES 2

Definition at line 61 of file NvmExpressPei.h.

◆ NVME_MEM_MAX_PAGES

#define NVME_MEM_MAX_PAGES

Value:

  (                                                                  \
  1 /* ASQ */ +                                                      \
  1 /* ACQ */ +                                                      \
  1 /* SQs */ +                                                      \
  1 /* CQs */ +                                                      \
  NVME_PRP_SIZE)                            /* PRPs */

Definition at line 68 of file NvmExpressPei.h.

◆ NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE

#define NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('N','V','P','C')

Definition at line 97 of file NvmExpressPei.h.

◆ NVME_POLL_INTERVAL

#define NVME_POLL_INTERVAL 100

Definition at line 79 of file NvmExpressPei.h.

◆ NVME_PRP_SIZE

#define NVME_PRP_SIZE (8)

Definition at line 66 of file NvmExpressPei.h.

Typedef Documentation

◆ PEI_NVME_CONTROLLER_PRIVATE_DATA

typedef struct _PEI_NVME_CONTROLLER_PRIVATE_DATA PEI_NVME_CONTROLLER_PRIVATE_DATA

Definition at line 40 of file NvmExpressPei.h.

◆ PEI_NVME_NAMESPACE_INFO

typedef struct _PEI_NVME_NAMESPACE_INFO PEI_NVME_NAMESPACE_INFO

Definition at line 39 of file NvmExpressPei.h.

Function Documentation

◆ GetDevicePathInstanceSize()

EFI_STATUS GetDevicePathInstanceSize	(	IN EFI_DEVICE_PATH_PROTOCOL *	DevicePath,
		OUT UINTN *	InstanceSize,
		OUT BOOLEAN *	EntireDevicePathEnd
	)

Get the size of the current device path instance.

Parameters

[in]	DevicePath	A pointer to the EFI_DEVICE_PATH_PROTOCOL structure.
[out]	InstanceSize	The size of the current device path instance.
[out]	EntireDevicePathEnd	Indicate whether the instance is the last one in the device path strucure.

Return values

EFI_SUCCESS	The size of the current device path instance is fetched.
Others	Fails to get the size of the current device path instance.

Definition at line 55 of file DevicePath.c.

◆ IoMmuAllocateBuffer()

EFI_STATUS IoMmuAllocateBuffer	(	IN UINTN	Pages,
		OUT VOID **	HostAddress,
		OUT EFI_PHYSICAL_ADDRESS *	DeviceAddress,
		OUT VOID **	Mapping
	)

Allocates pages that are suitable for an OperationBusMasterCommonBuffer or OperationBusMasterCommonBuffer64 mapping.

Parameters

Pages	The number of pages to allocate.
HostAddress	A pointer to store the base system memory address of the allocated range.
DeviceAddress	The resulting map address for the bus master PCI controller to use to access the hosts HostAddress.
Mapping	A resulting value to pass to Unmap().

Return values

EFI_SUCCESS	The requested memory pages were allocated.
EFI_UNSUPPORTED	Attributes is unsupported. The only legal attribute bits are MEMORY_WRITE_COMBINE and MEMORY_CACHED.
EFI_INVALID_PARAMETER	One or more parameters are invalid.
EFI_OUT_OF_RESOURCES	The memory pages could not be allocated.

Definition at line 170 of file DmaMem.c.

◆ IoMmuFreeBuffer()

EFI_STATUS IoMmuFreeBuffer	(	IN UINTN	Pages,
		IN VOID *	HostAddress,
		IN VOID *	Mapping
	)

Frees memory that was allocated with AllocateBuffer().

Parameters

Pages	The number of pages to free.
HostAddress	The base system memory address of the allocated range.
Mapping	The mapping value returned from Map().

Return values

EFI_SUCCESS	The requested memory pages were freed.
EFI_INVALID_PARAMETER	The memory range specified by HostAddress and Pages was not allocated with AllocateBuffer().

Definition at line 251 of file DmaMem.c.

◆ IoMmuMap()

EFI_STATUS IoMmuMap	(	IN EDKII_IOMMU_OPERATION	Operation,
		IN VOID *	HostAddress,
		IN OUT UINTN *	NumberOfBytes,
		OUT EFI_PHYSICAL_ADDRESS *	DeviceAddress,
		OUT VOID **	Mapping
	)

Provides the controller-specific addresses required to access system memory from a DMA bus master.

Parameters

Operation	Indicates if the bus master is going to read or write to system memory.
HostAddress	The system memory address to map to the PCI controller.
NumberOfBytes	On input the number of bytes to map. On output the number of bytes that were mapped.
DeviceAddress	The resulting map address for the bus master PCI controller to use to access the hosts HostAddress.
Mapping	A resulting value to pass to Unmap().

Return values

EFI_SUCCESS	The range was mapped for the returned NumberOfBytes.
EFI_UNSUPPORTED	The HostAddress cannot be mapped as a common buffer.
EFI_INVALID_PARAMETER	One or more parameters are invalid.
EFI_OUT_OF_RESOURCES	The request could not be completed due to a lack of resources.
EFI_DEVICE_ERROR	The system hardware could not map the requested address.

Definition at line 60 of file DmaMem.c.

◆ IoMmuUnmap()

EFI_STATUS IoMmuUnmap ( IN VOID * Mapping )

Completes the Map() operation and releases any corresponding resources.

Parameters

Mapping The mapping value returned from Map().

Return values

EFI_SUCCESS	The range was unmapped.
EFI_INVALID_PARAMETER	Mapping is not a value that was returned by Map().
EFI_DEVICE_ERROR	The data was not committed to the target system memory.

Definition at line 132 of file DmaMem.c.

◆ NvmeBuildDevicePath()

EFI_STATUS NvmeBuildDevicePath	(	IN PEI_NVME_CONTROLLER_PRIVATE_DATA *	Private,
		IN UINT32	NamespaceId,
		IN UINT64	NamespaceUuid,
		OUT UINTN *	DevicePathLength,
		OUT EFI_DEVICE_PATH_PROTOCOL **	DevicePath
	)

Build the device path for an Nvm Express device with given namespace identifier and namespace extended unique identifier.

Parameters

[in]	Private	A pointer to the PEI_NVME_CONTROLLER_PRIVATE_DATA data structure.
[in]	NamespaceId	The given namespace identifier.
[in]	NamespaceUuid	The given namespace extended unique identifier.
[out]	DevicePathLength	The length of the device path in bytes specified by DevicePath.
[out]	DevicePath	The device path of Nvm Express device.

Return values

EFI_SUCCESS	The operation succeeds.
EFI_INVALID_PARAMETER	The parameters are invalid.
EFI_OUT_OF_RESOURCES	The operation fails due to lack of resources.

Definition at line 177 of file DevicePath.c.

◆ NvmeHostControllerPpiInstallationCallback()

EFI_STATUS EFIAPI NvmeHostControllerPpiInstallationCallback	(	IN EFI_PEI_SERVICES **	PeiServices,
		IN EFI_PEI_NOTIFY_DESCRIPTOR *	NotifyDescriptor,
		IN VOID *	Ppi
	)

Callback for EDKII_NVM_EXPRESS_HOST_CONTROLLER_PPI installation.

Parameters

[in]	PeiServices	Pointer to PEI Services Table.
[in]	NotifyDescriptor	Pointer to the descriptor for the Notification event that caused this function to execute.
[in]	Ppi	Pointer to the PPI data associated with this function.

Return values

EFI_SUCCESS	The function completes successfully
Others	Cannot initialize Nvme controller from given EDKII_NVM_EXPRESS_HOST_CONTROLLER_PPI

Definition at line 682 of file NvmExpressPei.c.

◆ NvmeIsHcDevicePathValid()

EFI_STATUS NvmeIsHcDevicePathValid	(	IN EFI_DEVICE_PATH_PROTOCOL *	DevicePath,
		IN UINTN	DevicePathLength
	)

Check the validity of the device path of a NVM Express host controller.

Parameters

[in]	DevicePath	A pointer to the EFI_DEVICE_PATH_PROTOCOL structure.
[in]	DevicePathLength	The length of the device path.

Return values

EFI_SUCCESS	The device path is valid.
EFI_INVALID_PARAMETER	The device path is invalid.

Definition at line 105 of file DevicePath.c.

◆ NvmePciDevicePpiInstallationCallback()

EFI_STATUS EFIAPI NvmePciDevicePpiInstallationCallback	(	IN EFI_PEI_SERVICES **	PeiServices,
		IN EFI_PEI_NOTIFY_DESCRIPTOR *	NotifyDescriptor,
		IN VOID *	Ppi
	)

Callback for EDKII_PCI_DEVICE_PPI installation.

Parameters

[in]	PeiServices	Pointer to PEI Services Table.
[in]	NotifyDescriptor	Pointer to the descriptor for the Notification event that caused this function to execute.
[in]	Ppi	Pointer to the PPI data associated with this function.

Return values

EFI_SUCCESS	The function completes successfully
Others	Cannot initialize Nvme controller from given PCI_DEVICE_PPI

Definition at line 582 of file NvmExpressPei.c.

◆ NvmePeimEndOfPei()

EFI_STATUS EFIAPI NvmePeimEndOfPei	(	IN EFI_PEI_SERVICES **	PeiServices,
		IN EFI_PEI_NOTIFY_DESCRIPTOR *	NotifyDescriptor,
		IN VOID *	Ppi
	)

One notified function to cleanup the allocated resources at the end of PEI.

Parameters

[in]	PeiServices	Pointer to PEI Services Table.
[in]	NotifyDescriptor	Pointer to the descriptor for the Notification event that caused this function to execute.
[in]	Ppi	Pointer to the PPI data associated with this function.

Return values

EFI_SUCCESS The function completes successfully

Definition at line 212 of file NvmExpressPei.c.

◆ NvmeS3SkipThisController()

BOOLEAN NvmeS3SkipThisController	(	IN EFI_DEVICE_PATH_PROTOCOL *	HcDevicePath,
		IN UINTN	HcDevicePathLength
	)

Determine if a specific NVM Express controller can be skipped for S3 phase.

Parameters

[in]	HcDevicePath	Device path of the controller.
[in]	HcDevicePathLength	Length of the device path specified by HcDevicePath.

Return values

The	number of ports that need to be enumerated.

Definition at line 28 of file NvmExpressPeiS3.c.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO

◆ GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO2

◆ GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_NOTIFY

◆ GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_NVME_PASSTHRU

◆ GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_STROAGE_SECURITY

◆ IS_PCI_NVMHCI

◆ NVME_ACQ_SIZE

◆ NVME_ADMIN_QUEUE

◆ NVME_ASQ_SIZE

◆ NVME_CCQ_SIZE

◆ NVME_CONTROLLER_NSID

◆ NVME_CSQ_SIZE

◆ NVME_GENERIC_TIMEOUT

◆ NVME_IO_QUEUE

◆ NVME_MAX_QUEUES

◆ NVME_MEM_MAX_PAGES

◆ NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE

◆ NVME_POLL_INTERVAL

◆ NVME_PRP_SIZE

Typedef Documentation

◆ PEI_NVME_CONTROLLER_PRIVATE_DATA

◆ PEI_NVME_NAMESPACE_INFO

Function Documentation

◆ GetDevicePathInstanceSize()

◆ IoMmuAllocateBuffer()

◆ IoMmuFreeBuffer()

◆ IoMmuMap()

◆ IoMmuUnmap()

◆ NvmeBuildDevicePath()

◆ NvmeHostControllerPpiInstallationCallback()

◆ NvmeIsHcDevicePathValid()

◆ NvmePciDevicePpiInstallationCallback()

◆ NvmePeimEndOfPei()

◆ NvmeS3SkipThisController()