f39d30c44e22553a62050e9d4e757de6a3637a9c
[mirror_edk2.git] / ArmPkg / Library / ArmDmaLib / ArmDmaLib.c
1 /** @file
2 Generic ARM implementation of DmaLib.h
3
4 Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>
5
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
10
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14 **/
15
16 #include <PiDxe.h>
17 #include <Library/DebugLib.h>
18 #include <Library/DmaLib.h>
19 #include <Library/DxeServicesTableLib.h>
20 #include <Library/MemoryAllocationLib.h>
21 #include <Library/UefiBootServicesTableLib.h>
22 #include <Library/UncachedMemoryAllocationLib.h>
23 #include <Library/IoLib.h>
24 #include <Library/BaseMemoryLib.h>
25
26 #include <Protocol/Cpu.h>
27
28 typedef struct {
29 EFI_PHYSICAL_ADDRESS HostAddress;
30 VOID *BufferAddress;
31 UINTN NumberOfBytes;
32 DMA_MAP_OPERATION Operation;
33 BOOLEAN DoubleBuffer;
34 } MAP_INFO_INSTANCE;
35
36
37
38 STATIC EFI_CPU_ARCH_PROTOCOL *mCpu;
39
40 /**
41 Provides the DMA controller-specific addresses needed to access system memory.
42
43 Operation is relative to the DMA bus master.
44
45 @param Operation Indicates if the bus master is going to read or write to system memory.
46 @param HostAddress The system memory address to map to the DMA controller.
47 @param NumberOfBytes On input the number of bytes to map. On output the number of bytes
48 that were mapped.
49 @param DeviceAddress The resulting map address for the bus master controller to use to
50 access the hosts HostAddress.
51 @param Mapping A resulting value to pass to Unmap().
52
53 @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
54 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
55 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
56 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
57 @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
58
59 **/
60 EFI_STATUS
61 EFIAPI
62 DmaMap (
63 IN DMA_MAP_OPERATION Operation,
64 IN VOID *HostAddress,
65 IN OUT UINTN *NumberOfBytes,
66 OUT PHYSICAL_ADDRESS *DeviceAddress,
67 OUT VOID **Mapping
68 )
69 {
70 EFI_STATUS Status;
71 MAP_INFO_INSTANCE *Map;
72 VOID *Buffer;
73 EFI_GCD_MEMORY_SPACE_DESCRIPTOR GcdDescriptor;
74
75 if (HostAddress == NULL || NumberOfBytes == NULL || DeviceAddress == NULL || Mapping == NULL ) {
76 return EFI_INVALID_PARAMETER;
77 }
78
79 if (Operation >= MapOperationMaximum) {
80 return EFI_INVALID_PARAMETER;
81 }
82
83 *DeviceAddress = ConvertToPhysicalAddress (HostAddress);
84
85 // Remember range so we can flush on the other side
86 Map = AllocatePool (sizeof (MAP_INFO_INSTANCE));
87 if (Map == NULL) {
88 return EFI_OUT_OF_RESOURCES;
89 }
90
91 if ((((UINTN)HostAddress & (mCpu->DmaBufferAlignment - 1)) != 0) ||
92 ((*NumberOfBytes & (mCpu->DmaBufferAlignment - 1)) != 0)) {
93
94 // Get the cacheability of the region
95 Status = gDS->GetMemorySpaceDescriptor ((UINTN)HostAddress, &GcdDescriptor);
96 if (EFI_ERROR(Status)) {
97 goto FreeMapInfo;
98 }
99
100 // If the mapped buffer is not an uncached buffer
101 if ((GcdDescriptor.Attributes & (EFI_MEMORY_WB | EFI_MEMORY_WT)) != 0) {
102 //
103 // Operations of type MapOperationBusMasterCommonBuffer are only allowed
104 // on uncached buffers.
105 //
106 if (Operation == MapOperationBusMasterCommonBuffer) {
107 DEBUG ((EFI_D_ERROR,
108 "%a: Operation type 'MapOperationBusMasterCommonBuffer' is only supported\n"
109 "on memory regions that were allocated using DmaAllocateBuffer ()\n",
110 __FUNCTION__));
111 Status = EFI_UNSUPPORTED;
112 goto FreeMapInfo;
113 }
114
115 //
116 // If the buffer does not fill entire cache lines we must double buffer into
117 // uncached memory. Device (PCI) address becomes uncached page.
118 //
119 Map->DoubleBuffer = TRUE;
120 Status = DmaAllocateBuffer (EfiBootServicesData, EFI_SIZE_TO_PAGES (*NumberOfBytes), &Buffer);
121 if (EFI_ERROR (Status)) {
122 goto FreeMapInfo;
123 }
124
125 if (Operation == MapOperationBusMasterRead) {
126 CopyMem (Buffer, HostAddress, *NumberOfBytes);
127 }
128
129 *DeviceAddress = ConvertToPhysicalAddress ((UINTN)Buffer);
130 Map->BufferAddress = Buffer;
131 } else {
132 Map->DoubleBuffer = FALSE;
133 }
134 } else {
135 Map->DoubleBuffer = FALSE;
136
137 DEBUG_CODE_BEGIN ();
138
139 //
140 // The operation type check above only executes if the buffer happens to be
141 // misaligned with respect to CWG, but even if it is aligned, we should not
142 // allow arbitrary buffers to be used for creating consistent mappings.
143 // So duplicate the check here when running in DEBUG mode, just to assert
144 // that we are not trying to create a consistent mapping for cached memory.
145 //
146 Status = gDS->GetMemorySpaceDescriptor ((UINTN)HostAddress, &GcdDescriptor);
147 ASSERT_EFI_ERROR(Status);
148
149 ASSERT (Operation != MapOperationBusMasterCommonBuffer ||
150 (GcdDescriptor.Attributes & (EFI_MEMORY_WB | EFI_MEMORY_WT)) == 0);
151
152 DEBUG_CODE_END ();
153
154 // Flush the Data Cache (should not have any effect if the memory region is uncached)
155 mCpu->FlushDataCache (mCpu, (UINTN)HostAddress, *NumberOfBytes,
156 EfiCpuFlushTypeWriteBackInvalidate);
157 }
158
159 Map->HostAddress = (UINTN)HostAddress;
160 Map->NumberOfBytes = *NumberOfBytes;
161 Map->Operation = Operation;
162
163 *Mapping = Map;
164
165 return EFI_SUCCESS;
166
167 FreeMapInfo:
168 FreePool (Map);
169
170 return Status;
171 }
172
173
174 /**
175 Completes the DmaMapBusMasterRead(), DmaMapBusMasterWrite(), or DmaMapBusMasterCommonBuffer()
176 operation and releases any corresponding resources.
177
178 @param Mapping The mapping value returned from DmaMap*().
179
180 @retval EFI_SUCCESS The range was unmapped.
181 @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
182 @retval EFI_INVALID_PARAMETER An inconsistency was detected between the mapping type
183 and the DoubleBuffer field
184
185 **/
186 EFI_STATUS
187 EFIAPI
188 DmaUnmap (
189 IN VOID *Mapping
190 )
191 {
192 MAP_INFO_INSTANCE *Map;
193 EFI_STATUS Status;
194
195 if (Mapping == NULL) {
196 ASSERT (FALSE);
197 return EFI_INVALID_PARAMETER;
198 }
199
200 Map = (MAP_INFO_INSTANCE *)Mapping;
201
202 Status = EFI_SUCCESS;
203 if (Map->DoubleBuffer) {
204 ASSERT (Map->Operation != MapOperationBusMasterCommonBuffer);
205
206 if (Map->Operation == MapOperationBusMasterCommonBuffer) {
207 Status = EFI_INVALID_PARAMETER;
208 } else if (Map->Operation == MapOperationBusMasterWrite) {
209 CopyMem ((VOID *)(UINTN)Map->HostAddress, Map->BufferAddress,
210 Map->NumberOfBytes);
211 }
212
213 DmaFreeBuffer (EFI_SIZE_TO_PAGES (Map->NumberOfBytes), Map->BufferAddress);
214
215 } else {
216 if (Map->Operation == MapOperationBusMasterWrite) {
217 //
218 // Make sure we read buffer from uncached memory and not the cache
219 //
220 mCpu->FlushDataCache (mCpu, Map->HostAddress, Map->NumberOfBytes,
221 EfiCpuFlushTypeInvalidate);
222 }
223 }
224
225 FreePool (Map);
226
227 return Status;
228 }
229
230 /**
231 Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.
232 mapping.
233
234 @param MemoryType The type of memory to allocate, EfiBootServicesData or
235 EfiRuntimeServicesData.
236 @param Pages The number of pages to allocate.
237 @param HostAddress A pointer to store the base system memory address of the
238 allocated range.
239
240 @retval EFI_SUCCESS The requested memory pages were allocated.
241 @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
242 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
243 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
244 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
245
246 **/
247 EFI_STATUS
248 EFIAPI
249 DmaAllocateBuffer (
250 IN EFI_MEMORY_TYPE MemoryType,
251 IN UINTN Pages,
252 OUT VOID **HostAddress
253 )
254 {
255 VOID *Allocation;
256
257 if (HostAddress == NULL) {
258 return EFI_INVALID_PARAMETER;
259 }
260
261 //
262 // The only valid memory types are EfiBootServicesData and EfiRuntimeServicesData
263 //
264 // We used uncached memory to keep coherency
265 //
266 if (MemoryType == EfiBootServicesData) {
267 Allocation = UncachedAllocatePages (Pages);
268 } else if (MemoryType == EfiRuntimeServicesData) {
269 Allocation = UncachedAllocateRuntimePages (Pages);
270 } else {
271 return EFI_INVALID_PARAMETER;
272 }
273
274 if (Allocation == NULL) {
275 return EFI_OUT_OF_RESOURCES;
276 }
277
278 *HostAddress = Allocation;
279
280 return EFI_SUCCESS;
281 }
282
283
284 /**
285 Frees memory that was allocated with DmaAllocateBuffer().
286
287 @param Pages The number of pages to free.
288 @param HostAddress The base system memory address of the allocated range.
289
290 @retval EFI_SUCCESS The requested memory pages were freed.
291 @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
292 was not allocated with DmaAllocateBuffer().
293
294 **/
295 EFI_STATUS
296 EFIAPI
297 DmaFreeBuffer (
298 IN UINTN Pages,
299 IN VOID *HostAddress
300 )
301 {
302 if (HostAddress == NULL) {
303 return EFI_INVALID_PARAMETER;
304 }
305
306 UncachedFreePages (HostAddress, Pages);
307 return EFI_SUCCESS;
308 }
309
310
311 EFI_STATUS
312 EFIAPI
313 ArmDmaLibConstructor (
314 IN EFI_HANDLE ImageHandle,
315 IN EFI_SYSTEM_TABLE *SystemTable
316 )
317 {
318 EFI_STATUS Status;
319
320 // Get the Cpu protocol for later use
321 Status = gBS->LocateProtocol (&gEfiCpuArchProtocolGuid, NULL, (VOID **)&mCpu);
322 ASSERT_EFI_ERROR(Status);
323
324 return Status;
325 }
326