2 Generic ARM implementation of DmaLib.h
4 Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>
5 Copyright (c) 2015 - 2017, Linaro, Ltd. All rights reserved.<BR>
7 This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 #include <Library/BaseLib.h>
19 #include <Library/DebugLib.h>
20 #include <Library/DmaLib.h>
21 #include <Library/DxeServicesTableLib.h>
22 #include <Library/MemoryAllocationLib.h>
23 #include <Library/UefiBootServicesTableLib.h>
24 #include <Library/IoLib.h>
25 #include <Library/BaseMemoryLib.h>
27 #include <Protocol/Cpu.h>
30 EFI_PHYSICAL_ADDRESS HostAddress
;
33 DMA_MAP_OPERATION Operation
;
43 } UNCACHED_ALLOCATION
;
45 STATIC EFI_CPU_ARCH_PROTOCOL
*mCpu
;
46 STATIC LIST_ENTRY UncachedAllocationList
;
54 return (PHYSICAL_ADDRESS
)(UINTN
)Address
+ PcdGet64 (PcdArmDmaDeviceOffset
);
58 Provides the DMA controller-specific addresses needed to access system memory.
60 Operation is relative to the DMA bus master.
62 @param Operation Indicates if the bus master is going to read or write to system memory.
63 @param HostAddress The system memory address to map to the DMA controller.
64 @param NumberOfBytes On input the number of bytes to map. On output the number of bytes
66 @param DeviceAddress The resulting map address for the bus master controller to use to
67 access the hosts HostAddress.
68 @param Mapping A resulting value to pass to Unmap().
70 @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
71 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
72 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
73 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
74 @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
80 IN DMA_MAP_OPERATION Operation
,
82 IN OUT UINTN
*NumberOfBytes
,
83 OUT PHYSICAL_ADDRESS
*DeviceAddress
,
88 MAP_INFO_INSTANCE
*Map
;
90 EFI_GCD_MEMORY_SPACE_DESCRIPTOR GcdDescriptor
;
93 if (HostAddress
== NULL
|| NumberOfBytes
== NULL
|| DeviceAddress
== NULL
|| Mapping
== NULL
) {
94 return EFI_INVALID_PARAMETER
;
97 if (Operation
>= MapOperationMaximum
) {
98 return EFI_INVALID_PARAMETER
;
101 *DeviceAddress
= HostToDeviceAddress (HostAddress
);
103 // Remember range so we can flush on the other side
104 Map
= AllocatePool (sizeof (MAP_INFO_INSTANCE
));
106 return EFI_OUT_OF_RESOURCES
;
109 if (Operation
!= MapOperationBusMasterRead
&&
110 ((((UINTN
)HostAddress
& (mCpu
->DmaBufferAlignment
- 1)) != 0) ||
111 ((*NumberOfBytes
& (mCpu
->DmaBufferAlignment
- 1)) != 0))) {
113 // Get the cacheability of the region
114 Status
= gDS
->GetMemorySpaceDescriptor ((UINTN
)HostAddress
, &GcdDescriptor
);
115 if (EFI_ERROR(Status
)) {
119 // If the mapped buffer is not an uncached buffer
120 if ((GcdDescriptor
.Attributes
& (EFI_MEMORY_WB
| EFI_MEMORY_WT
)) != 0) {
122 // Operations of type MapOperationBusMasterCommonBuffer are only allowed
123 // on uncached buffers.
125 if (Operation
== MapOperationBusMasterCommonBuffer
) {
127 "%a: Operation type 'MapOperationBusMasterCommonBuffer' is only supported\n"
128 "on memory regions that were allocated using DmaAllocateBuffer ()\n",
130 Status
= EFI_UNSUPPORTED
;
135 // If the buffer does not fill entire cache lines we must double buffer
136 // into a suitably aligned allocation that allows us to invalidate the
137 // cache without running the risk of corrupting adjacent unrelated data.
138 // Note that pool allocations are guaranteed to be 8 byte aligned, so
139 // we only have to add (alignment - 8) worth of padding.
141 Map
->DoubleBuffer
= TRUE
;
142 AllocSize
= ALIGN_VALUE (*NumberOfBytes
, mCpu
->DmaBufferAlignment
) +
143 (mCpu
->DmaBufferAlignment
- 8);
144 Map
->BufferAddress
= AllocatePool (AllocSize
);
145 if (Map
->BufferAddress
== NULL
) {
146 Status
= EFI_OUT_OF_RESOURCES
;
150 Buffer
= ALIGN_POINTER (Map
->BufferAddress
, mCpu
->DmaBufferAlignment
);
151 *DeviceAddress
= HostToDeviceAddress (Buffer
);
154 // Get rid of any dirty cachelines covering the double buffer. This
155 // prevents them from being written back unexpectedly, potentially
156 // overwriting the data we receive from the device.
158 mCpu
->FlushDataCache (mCpu
, (UINTN
)Buffer
, *NumberOfBytes
,
159 EfiCpuFlushTypeWriteBack
);
161 Map
->DoubleBuffer
= FALSE
;
164 Map
->DoubleBuffer
= FALSE
;
169 // The operation type check above only executes if the buffer happens to be
170 // misaligned with respect to CWG, but even if it is aligned, we should not
171 // allow arbitrary buffers to be used for creating consistent mappings.
172 // So duplicate the check here when running in DEBUG mode, just to assert
173 // that we are not trying to create a consistent mapping for cached memory.
175 Status
= gDS
->GetMemorySpaceDescriptor ((UINTN
)HostAddress
, &GcdDescriptor
);
176 ASSERT_EFI_ERROR(Status
);
178 ASSERT (Operation
!= MapOperationBusMasterCommonBuffer
||
179 (GcdDescriptor
.Attributes
& (EFI_MEMORY_WB
| EFI_MEMORY_WT
)) == 0);
183 // Flush the Data Cache (should not have any effect if the memory region is uncached)
184 mCpu
->FlushDataCache (mCpu
, (UINTN
)HostAddress
, *NumberOfBytes
,
185 EfiCpuFlushTypeWriteBackInvalidate
);
188 Map
->HostAddress
= (UINTN
)HostAddress
;
189 Map
->NumberOfBytes
= *NumberOfBytes
;
190 Map
->Operation
= Operation
;
204 Completes the DmaMapBusMasterRead(), DmaMapBusMasterWrite(), or DmaMapBusMasterCommonBuffer()
205 operation and releases any corresponding resources.
207 @param Mapping The mapping value returned from DmaMap*().
209 @retval EFI_SUCCESS The range was unmapped.
210 @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
211 @retval EFI_INVALID_PARAMETER An inconsistency was detected between the mapping type
212 and the DoubleBuffer field
221 MAP_INFO_INSTANCE
*Map
;
225 if (Mapping
== NULL
) {
227 return EFI_INVALID_PARAMETER
;
230 Map
= (MAP_INFO_INSTANCE
*)Mapping
;
232 Status
= EFI_SUCCESS
;
233 if (Map
->DoubleBuffer
) {
234 ASSERT (Map
->Operation
== MapOperationBusMasterWrite
);
236 if (Map
->Operation
!= MapOperationBusMasterWrite
) {
237 Status
= EFI_INVALID_PARAMETER
;
239 Buffer
= ALIGN_POINTER (Map
->BufferAddress
, mCpu
->DmaBufferAlignment
);
241 mCpu
->FlushDataCache (mCpu
, (UINTN
)Buffer
, Map
->NumberOfBytes
,
242 EfiCpuFlushTypeInvalidate
);
244 CopyMem ((VOID
*)(UINTN
)Map
->HostAddress
, Buffer
, Map
->NumberOfBytes
);
246 FreePool (Map
->BufferAddress
);
249 if (Map
->Operation
== MapOperationBusMasterWrite
) {
251 // Make sure we read buffer from uncached memory and not the cache
253 mCpu
->FlushDataCache (mCpu
, Map
->HostAddress
, Map
->NumberOfBytes
,
254 EfiCpuFlushTypeInvalidate
);
264 Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.
267 @param MemoryType The type of memory to allocate, EfiBootServicesData or
268 EfiRuntimeServicesData.
269 @param Pages The number of pages to allocate.
270 @param HostAddress A pointer to store the base system memory address of the
273 @retval EFI_SUCCESS The requested memory pages were allocated.
274 @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
275 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
276 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
277 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
283 IN EFI_MEMORY_TYPE MemoryType
,
285 OUT VOID
**HostAddress
288 EFI_GCD_MEMORY_SPACE_DESCRIPTOR GcdDescriptor
;
291 UNCACHED_ALLOCATION
*Alloc
;
294 if (HostAddress
== NULL
) {
295 return EFI_INVALID_PARAMETER
;
298 if (MemoryType
== EfiBootServicesData
) {
299 Allocation
= AllocatePages (Pages
);
300 } else if (MemoryType
== EfiRuntimeServicesData
) {
301 Allocation
= AllocateRuntimePages (Pages
);
303 return EFI_INVALID_PARAMETER
;
306 if (Allocation
== NULL
) {
307 return EFI_OUT_OF_RESOURCES
;
310 // Get the cacheability of the region
311 Status
= gDS
->GetMemorySpaceDescriptor ((UINTN
)Allocation
, &GcdDescriptor
);
312 if (EFI_ERROR(Status
)) {
316 // Choose a suitable uncached memory type that is supported by the region
317 if (GcdDescriptor
.Capabilities
& EFI_MEMORY_WC
) {
318 MemType
= EFI_MEMORY_WC
;
319 } else if (GcdDescriptor
.Capabilities
& EFI_MEMORY_UC
) {
320 MemType
= EFI_MEMORY_UC
;
322 Status
= EFI_UNSUPPORTED
;
326 Alloc
= AllocatePool (sizeof *Alloc
);
331 Alloc
->HostAddress
= Allocation
;
332 Alloc
->NumPages
= Pages
;
333 Alloc
->Attributes
= GcdDescriptor
.Attributes
;
335 InsertHeadList (&UncachedAllocationList
, &Alloc
->Link
);
337 // Remap the region with the new attributes
338 Status
= gDS
->SetMemorySpaceAttributes ((PHYSICAL_ADDRESS
)(UINTN
)Allocation
,
339 EFI_PAGES_TO_SIZE (Pages
),
341 if (EFI_ERROR (Status
)) {
345 Status
= mCpu
->FlushDataCache (mCpu
,
346 (PHYSICAL_ADDRESS
)(UINTN
)Allocation
,
347 EFI_PAGES_TO_SIZE (Pages
),
348 EfiCpuFlushTypeInvalidate
);
349 if (EFI_ERROR (Status
)) {
353 *HostAddress
= Allocation
;
358 RemoveEntryList (&Alloc
->Link
);
362 FreePages (Allocation
, Pages
);
368 Frees memory that was allocated with DmaAllocateBuffer().
370 @param Pages The number of pages to free.
371 @param HostAddress The base system memory address of the allocated range.
373 @retval EFI_SUCCESS The requested memory pages were freed.
374 @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
375 was not allocated with DmaAllocateBuffer().
386 UNCACHED_ALLOCATION
*Alloc
;
390 if (HostAddress
== NULL
) {
391 return EFI_INVALID_PARAMETER
;
394 for (Link
= GetFirstNode (&UncachedAllocationList
), Found
= FALSE
;
395 !IsNull (&UncachedAllocationList
, Link
);
396 Link
= GetNextNode (&UncachedAllocationList
, Link
)) {
398 Alloc
= BASE_CR (Link
, UNCACHED_ALLOCATION
, Link
);
399 if (Alloc
->HostAddress
== HostAddress
&& Alloc
->NumPages
== Pages
) {
407 return EFI_INVALID_PARAMETER
;
410 RemoveEntryList (&Alloc
->Link
);
412 Status
= gDS
->SetMemorySpaceAttributes ((PHYSICAL_ADDRESS
)(UINTN
)HostAddress
,
413 EFI_PAGES_TO_SIZE (Pages
),
415 if (EFI_ERROR (Status
)) {
420 // If we fail to restore the original attributes, it is better to leak the
421 // memory than to return it to the heap
423 FreePages (HostAddress
, Pages
);
433 ArmDmaLibConstructor (
434 IN EFI_HANDLE ImageHandle
,
435 IN EFI_SYSTEM_TABLE
*SystemTable
438 InitializeListHead (&UncachedAllocationList
);
440 // Get the Cpu protocol for later use
441 return gBS
->LocateProtocol (&gEfiCpuArchProtocolGuid
, NULL
, (VOID
**)&mCpu
);