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