ArmPkg: only attempt buildin MmCommunicationDxe for AArch64
[mirror_edk2.git] / EmbeddedPkg / Include / Library / DmaLib.h
CommitLineData
1e57a462 1/** @file\r
2 DMA abstraction library APIs. Based on UEFI PCI IO protocol DMA abstractions.\r
3402aac7 3 At some point these functions will probably end up in a non PCI protocol\r
1e57a462 4 for embedded systems.\r
5\r
aaeef063 6 DMA Bus Master Read Operation:\r
3402aac7
RC
7 Call DmaMap() for MapOperationBusMasterRead.\r
8 Program the DMA Bus Master with the DeviceAddress returned by DmaMap().\r
9 Start the DMA Bus Master.\r
10 Wait for DMA Bus Master to complete the read operation.\r
1e57a462 11 Call DmaUnmap().\r
12\r
13 DMA Bus Master Write Operation:\r
aaeef063 14 Call DmaMap() for MapOperationBusMasterWrite.\r
15 Program the DMA Bus Master with the DeviceAddress returned by DmaMap().\r
16 Start the DMA Bus Master.\r
17 Wait for DMA Bus Master to complete the write operation.\r
1e57a462 18 Call DmaUnmap().\r
19\r
20 DMA Bus Master Common Buffer Operation:\r
3402aac7
RC
21 Call DmaAllocateBuffer() to allocate a common buffer.\r
22 Call DmaMap() for MapOperationBusMasterCommonBuffer.\r
23 Program the DMA Bus Master with the DeviceAddress returned by DmaMap().\r
24 The common buffer can now be accessed equally by the processor and the DMA bus master.\r
25 Call DmaUnmap().\r
1e57a462 26 Call DmaFreeBuffer().\r
27\r
28 Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>\r
29\r
878b807a 30 SPDX-License-Identifier: BSD-2-Clause-Patent\r
1e57a462 31\r
32**/\r
33\r
34#ifndef __DMA_LIB_H__\r
35#define __DMA_LIB_H__\r
36\r
aaeef063 37typedef enum {\r
38 ///\r
39 /// A read operation from system memory by a bus master.\r
40 ///\r
41 MapOperationBusMasterRead,\r
42 ///\r
43 /// A write operation from system memory by a bus master.\r
44 ///\r
45 MapOperationBusMasterWrite,\r
46 ///\r
47 /// Provides both read and write access to system memory by both the processor and a\r
48 /// bus master. The buffer is coherent from both the processor's and the bus master's point of view.\r
49 ///\r
50 MapOperationBusMasterCommonBuffer,\r
51 MapOperationMaximum\r
52} DMA_MAP_OPERATION;\r
1e57a462 53\r
54\r
55\r
56\r
3402aac7 57/**\r
aaeef063 58 Provides the DMA controller-specific addresses needed to access system memory.\r
3402aac7 59\r
aaeef063 60 Operation is relative to the DMA bus master.\r
3402aac7 61\r
aaeef063 62 @param Operation Indicates if the bus master is going to read or write to system memory.\r
63 @param HostAddress The system memory address to map to the DMA controller.\r
64 @param NumberOfBytes On input the number of bytes to map. On output the number of bytes\r
3402aac7 65 that were mapped.\r
aaeef063 66 @param DeviceAddress The resulting map address for the bus master controller to use to\r
3402aac7 67 access the hosts HostAddress.\r
aaeef063 68 @param Mapping A resulting value to pass to DmaUnmap().\r
3402aac7 69\r
aaeef063 70 @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.\r
3402aac7 71 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.\r
aaeef063 72 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
73 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r
74 @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.\r
3402aac7 75\r
1e57a462 76**/\r
77EFI_STATUS\r
78EFIAPI\r
79DmaMap (\r
80 IN DMA_MAP_OPERATION Operation,\r
aaeef063 81 IN VOID *HostAddress,\r
82 IN OUT UINTN *NumberOfBytes,\r
83 OUT PHYSICAL_ADDRESS *DeviceAddress,\r
84 OUT VOID **Mapping\r
1e57a462 85 );\r
86\r
87\r
88\r
89\r
3402aac7 90/**\r
aaeef063 91 Completes the DmaMapBusMasterRead, DmaMapBusMasterWrite, or DmaMapBusMasterCommonBuffer\r
92 operation and releases any corresponding resources.\r
3402aac7 93\r
aaeef063 94 @param Mapping The mapping value returned from DmaMap().\r
3402aac7 95\r
aaeef063 96 @retval EFI_SUCCESS The range was unmapped.\r
97 @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.\r
3402aac7 98\r
1e57a462 99**/\r
100EFI_STATUS\r
101EFIAPI\r
102DmaUnmap (\r
aaeef063 103 IN VOID *Mapping\r
1e57a462 104 );\r
105\r
106\r
3402aac7 107/**\r
aaeef063 108 Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.\r
3402aac7
RC
109 mapping.\r
110\r
aaeef063 111 @param MemoryType The type of memory to allocate, EfiBootServicesData or\r
3402aac7
RC
112 EfiRuntimeServicesData.\r
113 @param Pages The number of pages to allocate.\r
aaeef063 114 @param HostAddress A pointer to store the base system memory address of the\r
3402aac7 115 allocated range.\r
aaeef063 116\r
117 @retval EFI_SUCCESS The requested memory pages were allocated.\r
118 @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are\r
3402aac7 119 MEMORY_WRITE_COMBINE and MEMORY_CACHED.\r
aaeef063 120 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
3402aac7
RC
121 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.\r
122\r
1e57a462 123**/\r
124EFI_STATUS\r
125EFIAPI\r
126DmaAllocateBuffer (\r
127 IN EFI_MEMORY_TYPE MemoryType,\r
aaeef063 128 IN UINTN Pages,\r
129 OUT VOID **HostAddress\r
130 );\r
1e57a462 131\r
132\r
3402aac7 133/**\r
aaeef063 134 Frees memory that was allocated with DmaAllocateBuffer().\r
3402aac7
RC
135\r
136 @param Pages The number of pages to free.\r
137 @param HostAddress The base system memory address of the allocated range.\r
138\r
aaeef063 139 @retval EFI_SUCCESS The requested memory pages were freed.\r
140 @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages\r
141 was not allocated with DmaAllocateBuffer().\r
3402aac7 142\r
aaeef063 143**/\r
1e57a462 144EFI_STATUS\r
145EFIAPI\r
146DmaFreeBuffer (\r
aaeef063 147 IN UINTN Pages,\r
148 IN VOID *HostAddress\r
149 );\r
1e57a462 150\r
151\r
deef290f
AB
152/**\r
153 Allocates pages that are suitable for an DmaMap() of type\r
154 MapOperationBusMasterCommonBuffer mapping, at the requested alignment.\r
155\r
156 @param MemoryType The type of memory to allocate, EfiBootServicesData or\r
157 EfiRuntimeServicesData.\r
158 @param Pages The number of pages to allocate.\r
159 @param Alignment Alignment in bytes of the base of the returned\r
160 buffer (must be a power of 2)\r
161 @param HostAddress A pointer to store the base system memory address of the\r
162 allocated range.\r
1e57a462 163\r
deef290f
AB
164 @retval EFI_SUCCESS The requested memory pages were allocated.\r
165 @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are\r
166 MEMORY_WRITE_COMBINE and MEMORY_CACHED.\r
167 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
168 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.\r
169\r
170**/\r
171EFI_STATUS\r
172EFIAPI\r
173DmaAllocateAlignedBuffer (\r
174 IN EFI_MEMORY_TYPE MemoryType,\r
175 IN UINTN Pages,\r
176 IN UINTN Alignment,\r
177 OUT VOID **HostAddress\r
178 );\r
179\r
180\r
181#endif\r