MdeModulePkg/Include: Add IOMMU_PPI.
[mirror_edk2.git] / MdeModulePkg / Include / Ppi / IoMmu.h
1 /** @file
2 PEI IOMMU PPI.
3
4 Copyright (c) 2017, 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.
9
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.
12
13 **/
14
15
16 #ifndef __PEI_IOMMU_H__
17 #define __PEI_IOMMU_H__
18
19 //
20 // for EFI_ALLOCATE_TYPE
21 //
22 #include <Uefi.h>
23
24 //
25 // Include protocol for common definition
26 // EDKII_IOMMU_ACCESS_xxx
27 // EDKII_IOMMU_OPERATION
28 //
29 #include <Protocol/IoMmu.h>
30
31 //
32 // IOMMU Ppi GUID value
33 //
34 #define EDKII_IOMMU_PPI_GUID \
35 { \
36 0x70b0af26, 0xf847, 0x4bb6, { 0xaa, 0xb9, 0xcd, 0xe8, 0x4f, 0xc6, 0x14, 0x31 } \
37 }
38
39 //
40 // Forward reference for pure ANSI compatability
41 //
42 typedef struct _EDKII_IOMMU_PPI EDKII_IOMMU_PPI;
43
44 //
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.
48 //
49 #define EDKII_IOMMU_PPI_REVISION 0x00010000
50
51 /**
52 Set IOMMU attribute for a system memory.
53
54 If the IOMMU PPI exists, the system memory cannot be used
55 for DMA by default.
56
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).
60
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.
64
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
73 **/
74 typedef
75 EFI_STATUS
76 (EFIAPI *EDKII_PEI_IOMMU_SET_ATTRIBUTE)(
77 IN EDKII_IOMMU_PPI *This,
78 IN VOID *Mapping,
79 IN UINT64 IoMmuAccess
80 );
81
82 /**
83 Provides the controller-specific addresses required to access system memory from a
84 DMA bus master.
85
86 @param This The PPI instance pointer.
87 @param Operation Indicates if the bus master is going to read or write to system memory.
88 @param HostAddress The system memory address to map to the PCI controller.
89 @param NumberOfBytes On input the number of bytes to map. On output the number of bytes
90 that were mapped.
91 @param DeviceAddress The resulting map address for the bus master PCI controller to use to
92 access the hosts HostAddress.
93 @param Mapping A resulting value to pass to Unmap().
94
95 @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
96 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
97 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
98 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
99 @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
100
101 **/
102 typedef
103 EFI_STATUS
104 (EFIAPI *EDKII_PEI_IOMMU_MAP)(
105 IN EDKII_IOMMU_PPI *This,
106 IN EDKII_IOMMU_OPERATION Operation,
107 IN VOID *HostAddress,
108 IN OUT UINTN *NumberOfBytes,
109 OUT EFI_PHYSICAL_ADDRESS *DeviceAddress,
110 OUT VOID **Mapping
111 );
112
113 /**
114 Completes the Map() operation and releases any corresponding resources.
115
116 @param This The PPI instance pointer.
117 @param Mapping The mapping value returned from Map().
118
119 @retval EFI_SUCCESS The range was unmapped.
120 @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
121 @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
122 **/
123 typedef
124 EFI_STATUS
125 (EFIAPI *EDKII_PEI_IOMMU_UNMAP)(
126 IN EDKII_IOMMU_PPI *This,
127 IN VOID *Mapping
128 );
129
130 /**
131 Allocates pages that are suitable for an OperationBusMasterCommonBuffer or
132 OperationBusMasterCommonBuffer64 mapping.
133
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
139 allocated range.
140 @param Attributes The requested bit mask of attributes for the allocated range.
141
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 and MEMORY_CACHED.
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
148 **/
149 typedef
150 EFI_STATUS
151 (EFIAPI *EDKII_PEI_IOMMU_ALLOCATE_BUFFER)(
152 IN EDKII_IOMMU_PPI *This,
153 IN EFI_MEMORY_TYPE MemoryType,
154 IN UINTN Pages,
155 IN OUT VOID **HostAddress,
156 IN UINT64 Attributes
157 );
158
159 /**
160 Frees memory that was allocated with AllocateBuffer().
161
162 @param This The protocol instance pointer.
163 @param Pages The number of pages to free.
164 @param HostAddress The base system memory address of the allocated range.
165
166 @retval EFI_SUCCESS The requested memory pages were freed.
167 @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
168 was not allocated with AllocateBuffer().
169
170 **/
171 typedef
172 EFI_STATUS
173 (EFIAPI *EDKII_PEI_IOMMU_FREE_BUFFER)(
174 IN EDKII_IOMMU_PPI *This,
175 IN UINTN Pages,
176 IN VOID *HostAddress
177 );
178
179 ///
180 /// IOMMU PPI structure.
181 ///
182 struct _EDKII_IOMMU_PPI {
183 UINT64 Revision;
184 EDKII_PEI_IOMMU_SET_ATTRIBUTE SetAttribute;
185 EDKII_PEI_IOMMU_MAP Map;
186 EDKII_PEI_IOMMU_UNMAP Unmap;
187 EDKII_PEI_IOMMU_ALLOCATE_BUFFER AllocateBuffer;
188 EDKII_PEI_IOMMU_FREE_BUFFER FreeBuffer;
189 };
190
191 ///
192 /// IOMMU PPI GUID variable.
193 ///
194 extern EFI_GUID gEdkiiIoMmuPpiGuid;
195
196 #endif