Refix the previous issue.
[mirror_edk2.git] / MdePkg / Include / Library / UefiLib.h
1 /** @file
2 MDE UEFI library functions and macros
3
4 Copyright (c) 2006, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 **/
14
15 #ifndef __UEFI_LIB_H__
16 #define __UEFI_LIB_H__
17
18 //
19 // Unicode String Table
20 //
21 typedef struct {
22 CHAR8 *Language;
23 CHAR16 *UnicodeString;
24 } EFI_UNICODE_STRING_TABLE;
25
26 //
27 // EFI Lock Status
28 //
29 typedef enum {
30 EfiLockUninitialized = 0,
31 EfiLockReleased = 1,
32 EfiLockAcquired = 2
33 } EFI_LOCK_STATE;
34
35 //
36 // EFI Lock
37 //
38 typedef struct {
39 EFI_TPL Tpl;
40 EFI_TPL OwnerTpl;
41 EFI_LOCK_STATE Lock;
42 } EFI_LOCK;
43
44
45 /**
46 This function searches the list of configuration tables stored in the EFI System
47 Table for a table with a GUID that matches TableGuid. If a match is found,
48 then a pointer to the configuration table is returned in Table, and EFI_SUCCESS
49 is returned. If a matching GUID is not found, then EFI_NOT_FOUND is returned.
50
51 @param TableGuid Pointer to table's GUID type..
52 @param Table Pointer to the table associated with TableGuid in the EFI System Table.
53
54 @retval EFI_SUCCESS A configuration table matching TableGuid was found.
55 @retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found.
56
57 **/
58 EFI_STATUS
59 EFIAPI
60 EfiGetSystemConfigurationTable (
61 IN EFI_GUID *TableGuid,
62 OUT VOID **Table
63 );
64
65 /**
66 This function causes the notification function to be executed for every protocol
67 of type ProtocolGuid instance that exists in the system when this function is
68 invoked. In addition, every time a protocol of type ProtocolGuid instance is
69 installed or reinstalled, the notification function is also executed.
70
71 @param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired.
72 @param NotifyTpl Supplies the task priority level of the event notifications.
73 @param NotifyFunction Supplies the function to notify when the event is signaled.
74 @param NotifyContext The context parameter to pass to NotifyFunction.
75 @param Registration A pointer to a memory location to receive the registration value.
76
77 @return The notification event that was created.
78
79 **/
80 EFI_EVENT
81 EFIAPI
82 EfiCreateProtocolNotifyEvent(
83 IN EFI_GUID *ProtocolGuid,
84 IN EFI_TPL NotifyTpl,
85 IN EFI_EVENT_NOTIFY NotifyFunction,
86 IN VOID *NotifyContext, OPTIONAL
87 OUT VOID **Registration
88 );
89
90 /**
91 This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
92 This event is signaled with EfiNamedEventSignal(). This provide the ability for
93 one or more listeners on the same event named by the GUID specified by Name.
94
95 @param Name Supplies GUID name of the event.
96 @param NotifyTpl Supplies the task priority level of the event notifications.
97 @param NotifyFunction Supplies the function to notify when the event is signaled.
98 @param NotifyContext The context parameter to pass to NotifyFunction.
99 @param Registration A pointer to a memory location to receive the registration value.
100
101 @retval EFI_SUCCESS A named event was created.
102 @retval EFI_OUT_OF_RESOURCES There are not enough resource to create the named event.
103
104 **/
105 EFI_STATUS
106 EFIAPI
107 EfiNamedEventListen (
108 IN CONST EFI_GUID *Name,
109 IN EFI_TPL NotifyTpl,
110 IN EFI_EVENT_NOTIFY NotifyFunction,
111 IN CONST VOID *NotifyContext, OPTIONAL
112 OUT VOID *Registration OPTIONAL
113 );
114
115 /**
116 This function signals the named event specified by Name. The named event must
117 have been created with EfiNamedEventListen().
118
119 @param Name Supplies GUID name of the event.
120
121 @retval EFI_SUCCESS A named event was signaled.
122 @retval EFI_OUT_OF_RESOURCES There are not enough resource to signal the named event.
123
124 **/
125 EFI_STATUS
126 EFIAPI
127 EfiNamedEventSignal (
128 IN CONST EFI_GUID *Name
129 );
130
131 /**
132 This function initializes a basic mutual exclusion lock to the released state
133 and returns the lock. Each lock provides mutual exclusion access at its task
134 priority level. Since there is no preemption or multiprocessor support in EFI,
135 acquiring the lock only consists of raising to the locks TPL.
136
137 @param Lock A pointer to the lock data structure to initialize.
138 @param Priority EFI TPL associated with the lock.
139
140 @return The lock.
141
142 **/
143 EFI_LOCK *
144 EFIAPI
145 EfiInitializeLock (
146 IN OUT EFI_LOCK *Lock,
147 IN EFI_TPL Priority
148 );
149
150 /**
151 This macro initializes the contents of a basic mutual exclusion lock to the
152 released state. Each lock provides mutual exclusion access at its task
153 priority level. Since there is no preemption or multiprocessor support in EFI,
154 acquiring the lock only consists of raising to the locks TPL.
155
156 @param Lock A pointer to the lock data structure to initialize.
157 @param Priority The task priority level of the lock.
158
159 @return The lock.
160
161 **/
162 #define EFI_INITIALIZE_LOCK_VARIABLE(Priority) \
163 {Priority, EFI_TPL_APPLICATION, EfiLockReleased }
164
165
166 /**
167
168 Macro that calls DebugAssert() if an EFI_LOCK structure is not in the locked state.
169
170 If the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set,
171 then this macro evaluates the EFI_LOCK structure specified by Lock. If Lock
172 is not in the locked state, then DebugAssert() is called passing in the source
173 filename, source line number, and Lock.
174
175 If Lock is NULL, then ASSERT().
176
177 @param LockParameter A pointer to the lock to acquire.
178
179 **/
180 #define ASSERT_LOCKED(LockParameter) \
181 do { \
182 if (DebugAssertEnabled ()) { \
183 ASSERT (LockParameter != NULL); \
184 if ((LockParameter)->Lock != EfiLockAcquired) { \
185 _ASSERT (LockParameter not locked); \
186 } \
187 } \
188 } while (FALSE)
189
190
191 /**
192 This function raises the system's current task priority level to the task
193 priority level of the mutual exclusion lock. Then, it places the lock in the
194 acquired state.
195
196 @param Priority The task priority level of the lock.
197
198 **/
199 VOID
200 EFIAPI
201 EfiAcquireLock (
202 IN EFI_LOCK *Lock
203 );
204
205 /**
206 This function raises the system's current task priority level to the task
207 priority level of the mutual exclusion lock. Then, it attempts to place the
208 lock in the acquired state.
209
210 @param Lock A pointer to the lock to acquire.
211
212 @retval EFI_SUCCESS The lock was acquired.
213 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
214
215 **/
216 EFI_STATUS
217 EFIAPI
218 EfiAcquireLockOrFail (
219 IN EFI_LOCK *Lock
220 );
221
222 /**
223 This function transitions a mutual exclusion lock from the acquired state to
224 the released state, and restores the system's task priority level to its
225 previous level.
226
227 @param Lock A pointer to the lock to release.
228
229 **/
230 VOID
231 EFIAPI
232 EfiReleaseLock (
233 IN EFI_LOCK *Lock
234 );
235
236 /**
237 This function looks up a Unicode string in UnicodeStringTable. If Language is
238 a member of SupportedLanguages and a Unicode string is found in UnicodeStringTable
239 that matches the language code specified by Language, then it is returned in
240 UnicodeString.
241
242 @param Language A pointer to the ISO 639-2 language code for the
243 Unicode string to look up and return.
244 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
245 that the Unicode string table supports. Language
246 must be a member of this set.
247 @param UnicodeStringTable A pointer to the table of Unicode strings.
248 @param UnicodeString A pointer to the Unicode string from UnicodeStringTable
249 that matches the language specified by Language.
250
251 @retval EFI_SUCCESS The Unicode string that matches the language
252 specified by Language was found
253 in the table of Unicoide strings UnicodeStringTable,
254 and it was returned in UnicodeString.
255 @retval EFI_INVALID_PARAMETER Language is NULL.
256 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
257 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
258 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
259 @retval EFI_UNSUPPORTED The language specified by Language is not a
260 member of SupportedLanguages.
261 @retval EFI_UNSUPPORTED The language specified by Language is not
262 supported by UnicodeStringTable.
263
264 **/
265 EFI_STATUS
266 EFIAPI
267 LookupUnicodeString (
268 IN CONST CHAR8 *Language,
269 IN CONST CHAR8 *SupportedLanguages,
270 IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable,
271 OUT CHAR16 **UnicodeString
272 );
273
274 /**
275 This function adds a Unicode string to UnicodeStringTable.
276 If Language is a member of SupportedLanguages then UnicodeString is added to
277 UnicodeStringTable. New buffers are allocated for both Language and
278 UnicodeString. The contents of Language and UnicodeString are copied into
279 these new buffers. These buffers are automatically freed when
280 FreeUnicodeStringTable() is called.
281
282 @param Language A pointer to the ISO 639-2 language code for the Unicode
283 string to add.
284 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
285 that the Unicode string table supports.
286 Language must be a member of this set.
287 @param UnicodeStringTable A pointer to the table of Unicode strings.
288 @param UnicodeString A pointer to the Unicode string to add.
289
290 @retval EFI_SUCCESS The Unicode string that matches the language
291 specified by Language was found in the table of
292 Unicode strings UnicodeStringTable, and it was
293 returned in UnicodeString.
294 @retval EFI_INVALID_PARAMETER Language is NULL.
295 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
296 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
297 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
298 @retval EFI_ALREADY_STARTED A Unicode string with language Language is
299 already present in UnicodeStringTable.
300 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another
301 Unicode string to UnicodeStringTable.
302 @retval EFI_UNSUPPORTED The language specified by Language is not a
303 member of SupportedLanguages.
304
305 **/
306 EFI_STATUS
307 EFIAPI
308 AddUnicodeString (
309 IN CONST CHAR8 *Language,
310 IN CONST CHAR8 *SupportedLanguages,
311 IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable,
312 IN CONST CHAR16 *UnicodeString
313 );
314
315 /**
316 This function frees the table of Unicode strings in UnicodeStringTable.
317 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
318 Otherwise, each language code, and each Unicode string in the Unicode string
319 table are freed, and EFI_SUCCESS is returned.
320
321 @param UnicodeStringTable A pointer to the table of Unicode strings.
322
323 @retval EFI_SUCCESS The Unicode string table was freed.
324
325 **/
326 EFI_STATUS
327 EFIAPI
328 FreeUnicodeStringTable (
329 IN EFI_UNICODE_STRING_TABLE *UnicodeStringTable
330 );
331
332 /**
333 This function computes and returns the width of the Unicode character
334 specified by UnicodeChar.
335
336 @param UnicodeChar A Unicode character.
337
338 @retval 0 The width if UnicodeChar could not be determined.
339 @retval 1 UnicodeChar is a narrow glyph.
340 @retval 2 UnicodeChar is a wide glyph.
341
342 **/
343 UINTN
344 EFIAPI
345 GetGlyphWidth (
346 IN CHAR16 UnicodeChar
347 );
348
349 /**
350 This function computes and returns the display length of
351 the Null-terminated Unicode string specified by String.
352 If String is NULL, then 0 is returned.
353 If any of the widths of the Unicode characters in String
354 can not be determined, then 0 is returned.
355
356 @param String A pointer to a Null-terminated Unicode string.
357
358 @return The display length of the Null-terminated Unicode string specified by String.
359
360 **/
361 UINTN
362 EFIAPI
363 UnicodeStringDisplayLength (
364 IN CONST CHAR16 *String
365 );
366
367 //
368 // Functions that abstract early Framework contamination of UEFI.
369 //
370 /**
371 Signal a Ready to Boot Event.
372
373 Create a Ready to Boot Event. Signal it and close it. This causes other
374 events of the same event group to be signaled in other modules.
375
376 **/
377 VOID
378 EFIAPI
379 EfiSignalEventReadyToBoot (
380 VOID
381 );
382
383 /**
384 Signal a Legacy Boot Event.
385
386 Create a legacy Boot Event. Signal it and close it. This causes other
387 events of the same event group to be signaled in other modules.
388
389 **/
390 VOID
391 EFIAPI
392 EfiSignalEventLegacyBoot (
393 VOID
394 );
395
396 /**
397 Create a Legacy Boot Event.
398
399 Tiano extended the CreateEvent Type enum to add a legacy boot event type.
400 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
401 added and now it's possible to not voilate the UEFI specification by
402 declaring a GUID for the legacy boot event class. This library supports
403 the EDK/EFI 1.10 form and EDK II/UEFI 2.0 form and allows common code to
404 work both ways.
405
406 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
407
408 @retval EFI_SUCCESS Event was created.
409 @retval Other Event was not created.
410
411 **/
412 EFI_STATUS
413 EFIAPI
414 EfiCreateEventLegacyBoot (
415 OUT EFI_EVENT *LegacyBootEvent
416 );
417
418 /**
419 Create an EFI event in the Legacy Boot Event Group and allows
420 the caller to specify a notification function.
421
422 This function abstracts the creation of the Legacy Boot Event.
423 The Framework moved from a proprietary to UEFI 2.0 based mechanism.
424 This library abstracts the caller from how this event is created to prevent
425 to code form having to change with the version of the specification supported.
426 If LegacyBootEvent is NULL, then ASSERT().
427
428 @param NotifyTpl The task priority level of the event.
429 @param NotifyFunction The notification function to call when the event is signaled.
430 @param NotifyContext The content to pass to NotifyFunction when the event is signaled.
431 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
432
433 @retval EFI_SUCCESS Event was created.
434 @retval Other Event was not created.
435
436 **/
437 EFI_STATUS
438 EFIAPI
439 EfiCreateEventLegacyBootEx (
440 IN EFI_TPL NotifyTpl,
441 IN EFI_EVENT_NOTIFY NotifyFunction, OPTIONAL
442 IN VOID *NotifyContext, OPTIONAL
443 OUT EFI_EVENT *LegacyBootEvent
444 );
445
446 /**
447 Create a Read to Boot Event.
448
449 Tiano extended the CreateEvent Type enum to add a ready to boot event type.
450 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
451 added and now it's possible to not voilate the UEFI specification and use
452 the ready to boot event class defined in UEFI 2.0. This library supports
453 the EDK/EFI 1.10 form and EDKII/UEFI 2.0 form and allows common code to
454 work both ways.
455
456 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
457
458 @retval EFI_SUCCESS Event was created.
459 @retval Other Event was not created.
460
461 **/
462 EFI_STATUS
463 EFIAPI
464 EfiCreateEventReadyToBoot (
465 OUT EFI_EVENT *ReadyToBootEvent
466 );
467
468 /**
469 Create an EFI event in the Ready To Boot Event Group and allows
470 the caller to specify a notification function.
471
472 This function abstracts the creation of the Ready to Boot Event.
473 The Framework moved from a proprietary to UEFI 2.0 based mechanism.
474 This library abstracts the caller from how this event is created to prevent
475 to code form having to change with the version of the specification supported.
476 If ReadyToBootEvent is NULL, then ASSERT().
477
478 @param NotifyTpl The task priority level of the event.
479 @param NotifyFunction The notification function to call when the event is signaled.
480 @param NotifyContext The content to pass to NotifyFunction when the event is signaled.
481 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
482
483 @retval EFI_SUCCESS Event was created.
484 @retval Other Event was not created.
485
486 **/
487 EFI_STATUS
488 EFIAPI
489 EfiCreateEventReadyToBootEx (
490 IN EFI_TPL NotifyTpl,
491 IN EFI_EVENT_NOTIFY NotifyFunction, OPTIONAL
492 IN VOID *NotifyContext, OPTIONAL
493 OUT EFI_EVENT *ReadyToBootEvent
494 );
495
496 /**
497 Initialize a Firmware Volume (FV) Media Device Path node.
498
499 Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
500 so as we move to UEFI 2.0 support we must use a mechanism that conforms with
501 the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
502 device path is defined for Tiano extensions of device path. If the code
503 is compiled to conform with the UEFI 2.0 specification use the new device path
504 else use the old form for backwards compatability.
505
506 @param FvDevicePathNode Pointer to a FV device path node to initialize
507 @param NameGuid FV file name to use in FvDevicePathNode
508
509 **/
510 VOID
511 EFIAPI
512 EfiInitializeFwVolDevicepathNode (
513 IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode,
514 IN CONST EFI_GUID *NameGuid
515 );
516
517 /**
518 Check to see if the Firmware Volume (FV) Media Device Path is valid
519
520 Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
521 so as we move to UEFI 2.0 support we must use a mechanism that conforms with
522 the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
523 device path is defined for Tiano extensions of device path. If the code
524 is compiled to conform with the UEFI 2.0 specification use the new device path
525 else use the old form for backwards compatability. The return value to this
526 function points to a location in FvDevicePathNode and it does not allocate
527 new memory for the GUID pointer that is returned.
528
529 @param FvDevicePathNode Pointer to FV device path to check.
530
531 @retval NULL FvDevicePathNode is not valid.
532 @retval Other FvDevicePathNode is valid and pointer to NameGuid was returned.
533
534 **/
535 EFI_GUID *
536 EFIAPI
537 EfiGetNameGuidFromFwVolDevicePathNode (
538 IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode
539 );
540
541
542 #endif