4 Copyright (c) 2017 - 2018, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials are licensed and made available under
6 the terms and conditions of the BSD License that accompanies this distribution.
7 The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php.
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #ifndef __PEI_IOMMU_H__
17 #define __PEI_IOMMU_H__
20 // for EFI_ALLOCATE_TYPE
25 // Include protocol for common definition
26 // EDKII_IOMMU_ACCESS_xxx
27 // EDKII_IOMMU_OPERATION
29 #include <Protocol/IoMmu.h>
32 // IOMMU Ppi GUID value
34 #define EDKII_IOMMU_PPI_GUID \
36 0x70b0af26, 0xf847, 0x4bb6, { 0xaa, 0xb9, 0xcd, 0xe8, 0x4f, 0xc6, 0x14, 0x31 } \
40 // Forward reference for pure ANSI compatability
42 typedef struct _EDKII_IOMMU_PPI EDKII_IOMMU_PPI
;
45 // Revision The revision to which the IOMMU interface adheres.
46 // All future revisions must be backwards compatible.
47 // If a future version is not back wards compatible it is not the same GUID.
49 #define EDKII_IOMMU_PPI_REVISION 0x00010000
52 Set IOMMU attribute for a system memory.
54 If the IOMMU PPI exists, the system memory cannot be used
57 When a device requests a DMA access for a system memory,
58 the device driver need use SetAttribute() to update the IOMMU
59 attribute to request DMA access (read and/or write).
61 @param[in] This The PPI instance pointer.
62 @param[in] Mapping The mapping value returned from Map().
63 @param[in] IoMmuAccess The IOMMU access.
65 @retval EFI_SUCCESS The IoMmuAccess is set for the memory range specified by DeviceAddress and Length.
66 @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
67 @retval EFI_INVALID_PARAMETER IoMmuAccess specified an illegal combination of access.
68 @retval EFI_UNSUPPORTED The bit mask of IoMmuAccess is not supported by the IOMMU.
69 @retval EFI_UNSUPPORTED The IOMMU does not support the memory range specified by Mapping.
70 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to modify the IOMMU access.
71 @retval EFI_DEVICE_ERROR The IOMMU device reported an error while attempting the operation.
72 @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
73 not available to be allocated yet.
78 (EFIAPI
*EDKII_PEI_IOMMU_SET_ATTRIBUTE
)(
79 IN EDKII_IOMMU_PPI
*This
,
85 Provides the controller-specific addresses required to access system memory from a
88 @param This The PPI instance pointer.
89 @param Operation Indicates if the bus master is going to read or write to system memory.
90 @param HostAddress The system memory address to map to the PCI controller.
91 @param NumberOfBytes On input the number of bytes to map. On output the number of bytes
93 @param DeviceAddress The resulting map address for the bus master PCI controller to use to
94 access the hosts HostAddress.
95 @param Mapping A resulting value to pass to Unmap().
97 @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
98 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
99 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
100 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
101 @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
102 @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
103 not available to be allocated yet.
108 (EFIAPI
*EDKII_PEI_IOMMU_MAP
)(
109 IN EDKII_IOMMU_PPI
*This
,
110 IN EDKII_IOMMU_OPERATION Operation
,
111 IN VOID
*HostAddress
,
112 IN OUT UINTN
*NumberOfBytes
,
113 OUT EFI_PHYSICAL_ADDRESS
*DeviceAddress
,
118 Completes the Map() operation and releases any corresponding resources.
120 @param This The PPI instance pointer.
121 @param Mapping The mapping value returned from Map().
123 @retval EFI_SUCCESS The range was unmapped.
124 @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
125 @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
126 @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
127 not available to be allocated yet.
132 (EFIAPI
*EDKII_PEI_IOMMU_UNMAP
)(
133 IN EDKII_IOMMU_PPI
*This
,
138 Allocates pages that are suitable for an OperationBusMasterCommonBuffer or
139 OperationBusMasterCommonBuffer64 mapping.
141 @param This The PPI instance pointer.
142 @param MemoryType The type of memory to allocate, EfiBootServicesData or
143 EfiRuntimeServicesData.
144 @param Pages The number of pages to allocate.
145 @param HostAddress A pointer to store the base system memory address of the
147 @param Attributes The requested bit mask of attributes for the allocated range.
149 @retval EFI_SUCCESS The requested memory pages were allocated.
150 @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
151 MEMORY_WRITE_COMBINE, MEMORY_CACHED and DUAL_ADDRESS_CYCLE.
152 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
153 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
154 @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
155 not available to be allocated yet.
160 (EFIAPI
*EDKII_PEI_IOMMU_ALLOCATE_BUFFER
)(
161 IN EDKII_IOMMU_PPI
*This
,
162 IN EFI_MEMORY_TYPE MemoryType
,
164 IN OUT VOID
**HostAddress
,
169 Frees memory that was allocated with AllocateBuffer().
171 @param This The PPI instance pointer.
172 @param Pages The number of pages to free.
173 @param HostAddress The base system memory address of the allocated range.
175 @retval EFI_SUCCESS The requested memory pages were freed.
176 @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
177 was not allocated with AllocateBuffer().
178 @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
179 not available to be allocated yet.
184 (EFIAPI
*EDKII_PEI_IOMMU_FREE_BUFFER
)(
185 IN EDKII_IOMMU_PPI
*This
,
191 /// IOMMU PPI structure.
193 struct _EDKII_IOMMU_PPI
{
195 EDKII_PEI_IOMMU_SET_ATTRIBUTE SetAttribute
;
196 EDKII_PEI_IOMMU_MAP Map
;
197 EDKII_PEI_IOMMU_UNMAP Unmap
;
198 EDKII_PEI_IOMMU_ALLOCATE_BUFFER AllocateBuffer
;
199 EDKII_PEI_IOMMU_FREE_BUFFER FreeBuffer
;
203 /// IOMMU PPI GUID variable.
205 extern EFI_GUID gEdkiiIoMmuPpiGuid
;