Updated to reflect spec ECRs
[mirror_edk2.git] / MdePkg / Include / Uefi / UefiSpec.h
CommitLineData
959ccb23 1/** @file\r
2 Include file that supportes UEFI.\r
3\r
4 This include file must only contain things defined in the UEFI 2.0 specification.\r
5 If a code construct is defined in the UEFI 2.0 specification it must be included\r
6 by this include file.\r
7\r
8 Copyright (c) 2006 - 2007, Intel Corporation\r
9 All rights reserved. This program and the accompanying materials\r
10 are licensed and made available under the terms and conditions of the BSD License\r
11 which accompanies this distribution. The full text of the license may be found at\r
12 http://opensource.org/licenses/bsd-license.php\r
13\r
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
16\r
959ccb23 17**/\r
18\r
19#ifndef __UEFI_SPEC_H__\r
20#define __UEFI_SPEC_H__\r
21\r
22#include <Uefi/UefiMultiPhase.h>\r
23\r
24#include <Protocol/DevicePath.h>\r
25#include <Protocol/SimpleTextIn.h>\r
26#include <Protocol/SimpleTextOut.h>\r
27\r
959ccb23 28//\r
29// Enumeration of memory allocation.\r
30// \r
31typedef enum {\r
32 AllocateAnyPages,\r
33 AllocateMaxAddress,\r
34 AllocateAddress,\r
35 MaxAllocateType\r
36} EFI_ALLOCATE_TYPE;\r
37\r
5413e8e8 38//\r
39// Bit definitions for EFI_TIME.Daylight\r
40//\r
41#define EFI_TIME_ADJUST_DAYLIGHT 0x01\r
42#define EFI_TIME_IN_DAYLIGHT 0x02\r
43\r
44//\r
45// Value definition for EFI_TIME.TimeZone\r
46//\r
47#define EFI_UNSPECIFIED_TIMEZONE 0x07FF\r
959ccb23 48\r
49//\r
50// possible caching types for the memory range\r
51//\r
52#define EFI_MEMORY_UC 0x0000000000000001ULL\r
53#define EFI_MEMORY_WC 0x0000000000000002ULL\r
54#define EFI_MEMORY_WT 0x0000000000000004ULL\r
55#define EFI_MEMORY_WB 0x0000000000000008ULL\r
56#define EFI_MEMORY_UCE 0x0000000000000010ULL\r
57\r
58//\r
59// physical memory protection on range\r
60//\r
00edb218
A
61#define EFI_MEMORY_WP 0x0000000000001000ULL\r
62#define EFI_MEMORY_RP 0x0000000000002000ULL\r
63#define EFI_MEMORY_XP 0x0000000000004000ULL\r
959ccb23 64\r
65//\r
66// range requires a runtime mapping\r
67//\r
68#define EFI_MEMORY_RUNTIME 0x8000000000000000ULL\r
69\r
70#define EFI_MEMORY_DESCRIPTOR_VERSION 1\r
71typedef struct {\r
00edb218
A
72 UINT32 Type;\r
73 EFI_PHYSICAL_ADDRESS PhysicalStart;\r
74 EFI_VIRTUAL_ADDRESS VirtualStart;\r
75 UINT64 NumberOfPages;\r
76 UINT64 Attribute;\r
959ccb23 77} EFI_MEMORY_DESCRIPTOR;\r
78\r
79//\r
80// Build macros to find next EFI_MEMORY_DESCRIPTOR.\r
81// \r
82#define NextMemoryDescriptor(_Ptr, _Size) ((EFI_MEMORY_DESCRIPTOR *) (((UINT8 *) (_Ptr)) + (_Size)))\r
83#define NEXT_MEMORY_DESCRIPTOR(_Ptr, _Size) NextMemoryDescriptor (_Ptr, _Size)\r
84\r
85//\r
86// Declare forward referenced data structures\r
87//\r
88typedef struct _EFI_SYSTEM_TABLE EFI_SYSTEM_TABLE;\r
89\r
90/**\r
91 Allocates memory pages from the system.\r
92\r
93 @param Type The type of allocation to perform.\r
94 @param MemoryType The type of memory to allocate.\r
95 @param Pages The number of contiguous 4 KB pages to allocate.\r
96 @param Memory Pointer to a physical address. On input, the way in which the address is\r
97 used depends on the value of Type.\r
98\r
99 @retval EFI_SUCCESS The requested pages were allocated.\r
100 @retval EFI_INVALID_PARAMETER 1) Type is not AllocateAnyPages or\r
101 AllocateMaxAddress or AllocateAddress.\r
102 2) MemoryType is in the range\r
103 EfiMaxMemoryType..0x7FFFFFFF.\r
104 @retval EFI_OUT_OF_RESOURCES The pages could not be allocated.\r
105 @retval EFI_NOT_FOUND The requested pages could not be found.\r
106\r
107**/\r
108typedef\r
109EFI_STATUS\r
110(EFIAPI *EFI_ALLOCATE_PAGES) (\r
111 IN EFI_ALLOCATE_TYPE Type,\r
112 IN EFI_MEMORY_TYPE MemoryType,\r
113 IN UINTN Pages,\r
114 IN OUT EFI_PHYSICAL_ADDRESS *Memory\r
115 );\r
116\r
117/**\r
118 Frees memory pages.\r
119\r
120 @param Memory The base physical address of the pages to be freed.\r
121 @param Pages The number of contiguous 4 KB pages to free.\r
122\r
123 @retval EFI_SUCCESS The requested pages were freed.\r
124 @retval EFI_INVALID_PARAMETER Memory is not a page-aligned address or Pages is invalid.\r
125 @retval EFI_NOT_FOUND The requested memory pages were not allocated with\r
126 AllocatePages().\r
127\r
128**/\r
129typedef\r
130EFI_STATUS\r
131(EFIAPI *EFI_FREE_PAGES) (\r
132 IN EFI_PHYSICAL_ADDRESS Memory,\r
133 IN UINTN Pages\r
134 );\r
135\r
136/**\r
137 Returns the current memory map.\r
138\r
139 @param MemoryMapSize A pointer to the size, in bytes, of the MemoryMap buffer.\r
140 @param MemoryMap A pointer to the buffer in which firmware places the current memory\r
141 map.\r
142 @param MapKey A pointer to the location in which firmware returns the key for the\r
143 current memory map.\r
144 @param DescriptorSize A pointer to the location in which firmware returns the size, in bytes, of\r
145 an individual EFI_MEMORY_DESCRIPTOR.\r
146 @param DescriptorVersion A pointer to the location in which firmware returns the version number\r
147 associated with the EFI_MEMORY_DESCRIPTOR.\r
148\r
149 @retval EFI_SUCCESS The memory map was returned in the MemoryMap buffer.\r
150 @retval EFI_BUFFER_TOO_SMALL The MemoryMap buffer was too small. The current buffer size\r
151 needed to hold the memory map is returned in MemoryMapSize.\r
152 @retval EFI_INVALID_PARAMETER 1) MemoryMapSize is NULL.\r
153 2) The MemoryMap buffer is not too small and MemoryMap is\r
154 NULL.\r
155\r
156**/\r
157typedef\r
158EFI_STATUS\r
159(EFIAPI *EFI_GET_MEMORY_MAP) (\r
160 IN OUT UINTN *MemoryMapSize,\r
161 IN OUT EFI_MEMORY_DESCRIPTOR *MemoryMap,\r
162 OUT UINTN *MapKey,\r
163 OUT UINTN *DescriptorSize,\r
164 OUT UINT32 *DescriptorVersion\r
165 );\r
166\r
167/**\r
168 Allocates pool memory.\r
169\r
170 @param PoolType The type of pool to allocate.\r
171 @param Size The number of bytes to allocate from the pool.\r
172 @param Buffer A pointer to a pointer to the allocated buffer if the call succeeds;\r
173 undefined otherwise.\r
174\r
175 @retval EFI_SUCCESS The requested number of bytes was allocated.\r
176 @retval EFI_OUT_OF_RESOURCES The pool requested could not be allocated.\r
177 @retval EFI_INVALID_PARAMETER PoolType was invalid.\r
178\r
179**/\r
180typedef\r
181EFI_STATUS\r
182(EFIAPI *EFI_ALLOCATE_POOL) (\r
183 IN EFI_MEMORY_TYPE PoolType,\r
184 IN UINTN Size,\r
185 OUT VOID **Buffer\r
186 );\r
187\r
188/**\r
189 Returns pool memory to the system.\r
190\r
191 @param Buffer Pointer to the buffer to free.\r
192\r
193 @retval EFI_SUCCESS The memory was returned to the system.\r
194 @retval EFI_INVALID_PARAMETER Buffer was invalid.\r
195\r
196**/\r
197typedef\r
198EFI_STATUS\r
199(EFIAPI *EFI_FREE_POOL) (\r
200 IN VOID *Buffer\r
201 );\r
202\r
203/**\r
204 Changes the runtime addressing mode of EFI firmware from physical to virtual.\r
205\r
206 @param MemoryMapSize The size in bytes of VirtualMap.\r
207 @param DescriptorSize The size in bytes of an entry in the VirtualMap.\r
208 @param DescriptorVersion The version of the structure entries in VirtualMap.\r
209 @param VirtualMap An array of memory descriptors which contain new virtual\r
210 address mapping information for all runtime ranges.\r
211\r
212 @retval EFI_SUCCESS The virtual address map has been applied.\r
213 @retval EFI_UNSUPPORTED EFI firmware is not at runtime, or the EFI firmware is already in\r
214 virtual address mapped mode.\r
215 @retval EFI_INVALID_PARAMETER DescriptorSize or DescriptorVersion is invalid.\r
216 @retval EFI_NO_MAPPING A virtual address was not supplied for a range in the memory\r
217 map that requires a mapping.\r
218 @retval EFI_NOT_FOUND A virtual address was supplied for an address that is not found\r
219 in the memory map.\r
220\r
221**/\r
222typedef\r
223EFI_STATUS\r
224(EFIAPI *EFI_SET_VIRTUAL_ADDRESS_MAP) (\r
225 IN UINTN MemoryMapSize,\r
226 IN UINTN DescriptorSize,\r
227 IN UINT32 DescriptorVersion,\r
228 IN EFI_MEMORY_DESCRIPTOR *VirtualMap\r
229 );\r
230\r
231/**\r
232 Connects one or more drivers to a controller.\r
233\r
234 @param ControllerHandle The handle of the controller to which driver(s) are to be connected.\r
235 @param DriverImageHandle A pointer to an ordered list handles that support the\r
236 EFI_DRIVER_BINDING_PROTOCOL.\r
237 @param RemainingDevicePath A pointer to the device path that specifies a child of the\r
238 controller specified by ControllerHandle.\r
239 @param Recursive If TRUE, then ConnectController() is called recursively\r
240 until the entire tree of controllers below the controller specified\r
241 by ControllerHandle have been created. If FALSE, then\r
242 the tree of controllers is only expanded one level.\r
243\r
244 @retval EFI_SUCCESS 1) One or more drivers were connected to ControllerHandle.\r
245 2) No drivers were connected to ControllerHandle, but\r
246 RemainingDevicePath is not NULL, and it is an End Device\r
247 Path Node.\r
248 @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
249 @retval EFI_NOT_FOUND 1) There are no EFI_DRIVER_BINDING_PROTOCOL instances\r
250 present in the system.\r
251 2) No drivers were connected to ControllerHandle.\r
252\r
253**/\r
254typedef\r
255EFI_STATUS\r
256(EFIAPI *EFI_CONNECT_CONTROLLER) (\r
257 IN EFI_HANDLE ControllerHandle,\r
258 IN EFI_HANDLE *DriverImageHandle, OPTIONAL\r
259 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath, OPTIONAL\r
260 IN BOOLEAN Recursive\r
261 );\r
262\r
263/**\r
264 Disconnects one or more drivers from a controller.\r
265\r
266 @param ControllerHandle The handle of the controller from which driver(s) are to be disconnected.\r
267 @param DriverImageHandle The driver to disconnect from ControllerHandle.\r
268 @param ChildHandle The handle of the child to destroy.\r
269\r
270 @retval EFI_SUCCESS 1) One or more drivers were disconnected from the controller.\r
271 2) On entry, no drivers are managing ControllerHandle.\r
272 3) DriverImageHandle is not NULL, and on entry\r
273 DriverImageHandle is not managing ControllerHandle.\r
274\r
275 @retval EFI_INVALID_PARAMETER One ore more parameters are invalid.\r
276 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to disconnect any drivers from\r
277 ControllerHandle.\r
278 @retval EFI_DEVICE_ERROR The controller could not be disconnected because of a device error.\r
279\r
280**/\r
281typedef\r
282EFI_STATUS\r
283(EFIAPI *EFI_DISCONNECT_CONTROLLER) (\r
284 IN EFI_HANDLE ControllerHandle,\r
285 IN EFI_HANDLE DriverImageHandle, OPTIONAL\r
286 IN EFI_HANDLE ChildHandle OPTIONAL\r
287 );\r
288\r
289\r
290\r
291//\r
292// ConvertPointer DebugDisposition type.\r
293//\r
294#define EFI_OPTIONAL_PTR 0x00000001\r
295#define EFI_OPTIONAL_POINTER EFI_OPTIONAL_PTR\r
296\r
297/**\r
298 Determines the new virtual address that is to be used on subsequent memory accesses.\r
299\r
300 @param DebugDisposition Supplies type information for the pointer being converted.\r
301 @param Address A pointer to a pointer that is to be fixed to be the value needed\r
302 for the new virtual address mappings being applied.\r
303\r
304 @retval EFI_SUCCESS The pointer pointed to by Address was modified.\r
305 @retval EFI_INVALID_PARAMETER 1) Address is NULL.\r
306 2) *Address is NULL and DebugDisposition does\r
307 not have the EFI_OPTIONAL_PTR bit set.\r
308 @retval EFI_NOT_FOUND The pointer pointed to by Address was not found to be part\r
309 of the current memory map. This is normally fatal.\r
310\r
311**/\r
312typedef\r
313EFI_STATUS\r
314(EFIAPI *EFI_CONVERT_POINTER) (\r
315 IN UINTN DebugDisposition,\r
316 IN OUT VOID **Address\r
317 );\r
318\r
319\r
320//\r
93ce5aca
A
321