2 The NvmExpressPei driver is used to manage non-volatile memory subsystem
3 which follows NVM Express specification at PEI phase.
5 Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>
7 SPDX-License-Identifier: BSD-2-Clause-Patent
11 #ifndef _NVM_EXPRESS_PEI_H_
12 #define _NVM_EXPRESS_PEI_H_
16 #include <IndustryStandard/Nvme.h>
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>
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>
34 // Structure forward declarations
36 typedef struct _PEI_NVME_NAMESPACE_INFO PEI_NVME_NAMESPACE_INFO
;
37 typedef struct _PEI_NVME_CONTROLLER_PRIVATE_DATA PEI_NVME_CONTROLLER_PRIVATE_DATA
;
39 #include "NvmExpressPeiHci.h"
40 #include "NvmExpressPeiPassThru.h"
41 #include "NvmExpressPeiBlockIo.h"
42 #include "NvmExpressPeiStorageSecurity.h"
45 // NVME PEI driver implementation related definitions
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
54 #define NVME_MEM_MAX_PAGES \
60 NVME_PRP_SIZE) /* PRPs */
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
68 // Nvme namespace data structure.
70 struct _PEI_NVME_NAMESPACE_INFO
{
73 EFI_PEI_BLOCK_IO2_MEDIA Media
;
75 PEI_NVME_CONTROLLER_PRIVATE_DATA
*Controller
;
78 #define NVME_CONTROLLER_NSID 0
81 // Unique signature for private data structure.
83 #define NVME_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('N','V','P','C')
86 // Nvme controller private data structure.
88 struct _PEI_NVME_CONTROLLER_PRIVATE_DATA
{
91 EFI_NVM_EXPRESS_PASS_THRU_MODE PassThruMode
;
92 UINTN DevicePathLength
;
93 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
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
;
106 // Pointer to identify controller data
108 NVME_ADMIN_CONTROLLER_DATA
*ControllerData
;
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
122 // Pointers to 4kB aligned submission & completion queues
124 NVME_SQ
*SqBuffer
[NVME_MAX_QUEUES
];
125 NVME_CQ
*CqBuffer
[NVME_MAX_QUEUES
];
128 // Submission and completion queue indices
130 NVME_SQTDBL SqTdbl
[NVME_MAX_QUEUES
];
131 NVME_CQHDBL CqHdbl
[NVME_MAX_QUEUES
];
133 UINT8 Pt
[NVME_MAX_QUEUES
];
134 UINT16 Cid
[NVME_MAX_QUEUES
];
137 // Nvme controller capabilities
142 // Namespaces information on the controller
144 UINT32 ActiveNamespaceNum
;
145 PEI_NVME_NAMESPACE_INFO
*NamespaceInfo
;
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)
161 // Internal functions
165 Allocates pages that are suitable for an OperationBusMasterCommonBuffer or
166 OperationBusMasterCommonBuffer64 mapping.
168 @param Pages The number of pages to allocate.
169 @param HostAddress A pointer to store the base system memory address of the
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().
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.
183 IoMmuAllocateBuffer (
185 OUT VOID
**HostAddress
,
186 OUT EFI_PHYSICAL_ADDRESS
*DeviceAddress
,
191 Frees memory that was allocated with AllocateBuffer().
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().
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().
205 IN VOID
*HostAddress
,
210 Provides the controller-specific addresses required to access system memory from a
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
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().
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.
230 IN EDKII_IOMMU_OPERATION Operation
,
231 IN VOID
*HostAddress
,
232 IN OUT UINTN
*NumberOfBytes
,
233 OUT EFI_PHYSICAL_ADDRESS
*DeviceAddress
,
238 Completes the Map() operation and releases any corresponding resources.
240 @param Mapping The mapping value returned from Map().
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.
252 One notified function to cleanup the allocated resources at the end of PEI.
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.
259 @retval EFI_SUCCESS The function completes successfully
265 IN EFI_PEI_SERVICES
**PeiServices
,
266 IN EFI_PEI_NOTIFY_DESCRIPTOR
*NotifyDescriptor
,
271 Get the size of the current device path instance.
273 @param[in] DevicePath A pointer to the EFI_DEVICE_PATH_PROTOCOL
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.
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.
284 GetDevicePathInstanceSize (
285 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
286 OUT UINTN
*InstanceSize
,
287 OUT BOOLEAN
*EntireDevicePathEnd
291 Check the validity of the device path of a NVM Express host controller.
293 @param[in] DevicePath A pointer to the EFI_DEVICE_PATH_PROTOCOL
295 @param[in] DevicePathLength The length of the device path.
297 @retval EFI_SUCCESS The device path is valid.
298 @retval EFI_INVALID_PARAMETER The device path is invalid.
302 NvmeIsHcDevicePathValid (
303 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
304 IN UINTN DevicePathLength
308 Build the device path for an Nvm Express device with given namespace identifier
309 and namespace extended unique identifier.
311 @param[in] Private A pointer to the PEI_NVME_CONTROLLER_PRIVATE_DATA
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
317 @param[out] DevicePath The device path of Nvm Express device.
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.
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
334 Determine if a specific NVM Express controller can be skipped for S3 phase.
336 @param[in] HcDevicePath Device path of the controller.
337 @param[in] HcDevicePathLength Length of the device path specified by
340 @retval The number of ports that need to be enumerated.
344 NvmeS3SkipThisController (
345 IN EFI_DEVICE_PATH_PROTOCOL
*HcDevicePath
,
346 IN UINTN HcDevicePathLength