MdeModulePkg/UefiHiiLib: Fix incorrect check for string length
[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
30 This program and the accompanying materials\r
31 are licensed and made available under the terms and conditions of the BSD License\r
32 which accompanies this distribution. The full text of the license may be found at\r
33 http://opensource.org/licenses/bsd-license.php\r
34\r
35 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
36 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
37\r
38**/\r
39\r
40#ifndef __DMA_LIB_H__\r
41#define __DMA_LIB_H__\r
42\r
aaeef063 43typedef enum {\r
44 ///\r
45 /// A read operation from system memory by a bus master.\r
46 ///\r
47 MapOperationBusMasterRead,\r
48 ///\r
49 /// A write operation from system memory by a bus master.\r
50 ///\r
51 MapOperationBusMasterWrite,\r
52 ///\r
53 /// Provides both read and write access to system memory by both the processor and a\r
54 /// bus master. The buffer is coherent from both the processor's and the bus master's point of view.\r
55 ///\r
56 MapOperationBusMasterCommonBuffer,\r
57 MapOperationMaximum\r
58} DMA_MAP_OPERATION;\r
1e57a462 59\r
60\r
61\r
62\r
3402aac7 63/**\r
aaeef063 64 Provides the DMA controller-specific addresses needed to access system memory.\r
3402aac7 65\r
aaeef063 66 Operation is relative to the DMA bus master.\r
3402aac7 67\r
aaeef063 68 @param Operation Indicates if the bus master is going to read or write to system memory.\r
69 @param HostAddress The system memory address to map to the DMA controller.\r
70 @param NumberOfBytes On input the number of bytes to map. On output the number of bytes\r
3402aac7 71 that were mapped.\r
aaeef063 72 @param DeviceAddress The resulting map address for the bus master controller to use to\r
3402aac7 73 access the hosts HostAddress.\r
aaeef063 74 @param Mapping A resulting value to pass to DmaUnmap().\r
3402aac7 75\r
aaeef063 76 @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.\r
3402aac7 77 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.\r
aaeef063 78 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
79 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r
80 @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.\r
3402aac7 81\r
1e57a462 82**/\r
83EFI_STATUS\r
84EFIAPI\r
85DmaMap (\r
86 IN DMA_MAP_OPERATION Operation,\r
aaeef063 87 IN VOID *HostAddress,\r
88 IN OUT UINTN *NumberOfBytes,\r
89 OUT PHYSICAL_ADDRESS *DeviceAddress,\r
90 OUT VOID **Mapping\r
1e57a462 91 );\r
92\r
93\r
94\r
95\r
3402aac7 96/**\r
aaeef063 97 Completes the DmaMapBusMasterRead, DmaMapBusMasterWrite, or DmaMapBusMasterCommonBuffer\r
98 operation and releases any corresponding resources.\r
3402aac7 99\r
aaeef063 100 @param Mapping The mapping value returned from DmaMap().\r
3402aac7 101\r
aaeef063 102 @retval EFI_SUCCESS The range was unmapped.\r
103 @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.\r
3402aac7 104\r
1e57a462 105**/\r
106EFI_STATUS\r
107EFIAPI\r
108DmaUnmap (\r
aaeef063 109 IN VOID *Mapping\r
1e57a462 110 );\r
111\r
112\r
3402aac7 113/**\r
aaeef063 114 Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.\r
3402aac7
RC
115 mapping.\r
116\r
aaeef063 117 @param MemoryType The type of memory to allocate, EfiBootServicesData or\r
3402aac7
RC
118 EfiRuntimeServicesData.\r
119 @param Pages The number of pages to allocate.\r
aaeef063 120 @param HostAddress A pointer to store the base system memory address of the\r
3402aac7 121 allocated range.\r
aaeef063 122\r
123 @retval EFI_SUCCESS The requested memory pages were allocated.\r
124 @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are\r
3402aac7 125 MEMORY_WRITE_COMBINE and MEMORY_CACHED.\r
aaeef063 126 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
3402aac7
RC
127 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.\r
128\r
1e57a462 129**/\r
130EFI_STATUS\r
131EFIAPI\r
132DmaAllocateBuffer (\r
133 IN EFI_MEMORY_TYPE MemoryType,\r
aaeef063 134 IN UINTN Pages,\r
135 OUT VOID **HostAddress\r
136 );\r
1e57a462 137\r
138\r
3402aac7 139/**\r
aaeef063 140 Frees memory that was allocated with DmaAllocateBuffer().\r
3402aac7
RC
141\r
142 @param Pages The number of pages to free.\r
143 @param HostAddress The base system memory address of the allocated range.\r
144\r
aaeef063 145 @retval EFI_SUCCESS The requested memory pages were freed.\r
146 @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages\r
147 was not allocated with DmaAllocateBuffer().\r
3402aac7 148\r
aaeef063 149**/\r
1e57a462 150EFI_STATUS\r
151EFIAPI\r
152DmaFreeBuffer (\r
aaeef063 153 IN UINTN Pages,\r
154 IN VOID *HostAddress\r
155 );\r
1e57a462 156\r
157\r
3402aac7 158#endif\r
1e57a462 159\r