4 Copyright (c) 2017 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
9 #ifndef __PEI_IOMMU_H__
10 #define __PEI_IOMMU_H__
13 // for EFI_ALLOCATE_TYPE
18 // Include protocol for common definition
19 // EDKII_IOMMU_ACCESS_xxx
20 // EDKII_IOMMU_OPERATION
22 #include <Protocol/IoMmu.h>
25 // IOMMU Ppi GUID value
27 #define EDKII_IOMMU_PPI_GUID \
29 0x70b0af26, 0xf847, 0x4bb6, { 0xaa, 0xb9, 0xcd, 0xe8, 0x4f, 0xc6, 0x14, 0x31 } \
33 // Forward reference for pure ANSI compatability
35 typedef struct _EDKII_IOMMU_PPI EDKII_IOMMU_PPI
;
38 // Revision The revision to which the IOMMU interface adheres.
39 // All future revisions must be backwards compatible.
40 // If a future version is not back wards compatible it is not the same GUID.
42 #define EDKII_IOMMU_PPI_REVISION 0x00010000
45 Set IOMMU attribute for a system memory.
47 If the IOMMU PPI exists, the system memory cannot be used
50 When a device requests a DMA access for a system memory,
51 the device driver need use SetAttribute() to update the IOMMU
52 attribute to request DMA access (read and/or write).
54 @param[in] This The PPI instance pointer.
55 @param[in] Mapping The mapping value returned from Map().
56 @param[in] IoMmuAccess The IOMMU access.
58 @retval EFI_SUCCESS The IoMmuAccess is set for the memory range specified by DeviceAddress and Length.
59 @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
60 @retval EFI_INVALID_PARAMETER IoMmuAccess specified an illegal combination of access.
61 @retval EFI_UNSUPPORTED The bit mask of IoMmuAccess is not supported by the IOMMU.
62 @retval EFI_UNSUPPORTED The IOMMU does not support the memory range specified by Mapping.
63 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to modify the IOMMU access.
64 @retval EFI_DEVICE_ERROR The IOMMU device reported an error while attempting the operation.
65 @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
66 not available to be allocated yet.
71 (EFIAPI
*EDKII_PEI_IOMMU_SET_ATTRIBUTE
)(
72 IN EDKII_IOMMU_PPI
*This
,
78 Provides the controller-specific addresses required to access system memory from a
81 @param This The PPI instance pointer.
82 @param Operation Indicates if the bus master is going to read or write to system memory.
83 @param HostAddress The system memory address to map to the PCI controller.
84 @param NumberOfBytes On input the number of bytes to map. On output the number of bytes
86 @param DeviceAddress The resulting map address for the bus master PCI controller to use to
87 access the hosts HostAddress.
88 @param Mapping A resulting value to pass to Unmap().
90 @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
91 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
92 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
93 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
94 @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
95 @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
96 not available to be allocated yet.
101 (EFIAPI
*EDKII_PEI_IOMMU_MAP
)(
102 IN EDKII_IOMMU_PPI
*This
,
103 IN EDKII_IOMMU_OPERATION Operation
,
104 IN VOID
*HostAddress
,
105 IN OUT UINTN
*NumberOfBytes
,
106 OUT EFI_PHYSICAL_ADDRESS
*DeviceAddress
,
111 Completes the Map() operation and releases any corresponding resources.
113 @param This The PPI instance pointer.
114 @param Mapping The mapping value returned from Map().
116 @retval EFI_SUCCESS The range was unmapped.
117 @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
118 @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
119 @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
120 not available to be allocated yet.
125 (EFIAPI
*EDKII_PEI_IOMMU_UNMAP
)(
126 IN EDKII_IOMMU_PPI
*This
,
131 Allocates pages that are suitable for an OperationBusMasterCommonBuffer or
132 OperationBusMasterCommonBuffer64 mapping.
134 @param This The PPI instance pointer.
135 @param MemoryType The type of memory to allocate, EfiBootServicesData or
136 EfiRuntimeServicesData.
137 @param Pages The number of pages to allocate.
138 @param HostAddress A pointer to store the base system memory address of the
140 @param Attributes The requested bit mask of attributes for the allocated range.
142 @retval EFI_SUCCESS The requested memory pages were allocated.
143 @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
144 MEMORY_WRITE_COMBINE, MEMORY_CACHED and DUAL_ADDRESS_CYCLE.
145 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
146 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
147 @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
148 not available to be allocated yet.
153 (EFIAPI
*EDKII_PEI_IOMMU_ALLOCATE_BUFFER
)(
154 IN EDKII_IOMMU_PPI
*This
,
155 IN EFI_MEMORY_TYPE MemoryType
,
157 IN OUT VOID
**HostAddress
,
162 Frees memory that was allocated with AllocateBuffer().
164 @param This The PPI instance pointer.
165 @param Pages The number of pages to free.
166 @param HostAddress The base system memory address of the allocated range.
168 @retval EFI_SUCCESS The requested memory pages were freed.
169 @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
170 was not allocated with AllocateBuffer().
171 @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
172 not available to be allocated yet.
177 (EFIAPI
*EDKII_PEI_IOMMU_FREE_BUFFER
)(
178 IN EDKII_IOMMU_PPI
*This
,
184 /// IOMMU PPI structure.
186 struct _EDKII_IOMMU_PPI
{
188 EDKII_PEI_IOMMU_SET_ATTRIBUTE SetAttribute
;
189 EDKII_PEI_IOMMU_MAP Map
;
190 EDKII_PEI_IOMMU_UNMAP Unmap
;
191 EDKII_PEI_IOMMU_ALLOCATE_BUFFER AllocateBuffer
;
192 EDKII_PEI_IOMMU_FREE_BUFFER FreeBuffer
;
196 /// IOMMU PPI GUID variable.
198 extern EFI_GUID gEdkiiIoMmuPpiGuid
;