1) Added BIT0, BIT1, …, BIT63 to the Base Defines
[mirror_edk2.git] / MdePkg / Include / Library / UefiLib.h
1 /** @file
2 MDE UEFI library functions and macros
3
4 Copyright (c) 2006 - 2007, 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 Returns the current TPL.
133
134 This function returns the current TPL. There is no EFI service to directly
135 retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
136 the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level
137 can then immediately be restored back to the current TPL level with a call
138 to RestoreTPL().
139
140 @param VOID
141
142 @retvale EFI_TPL The current TPL.
143
144 **/
145 EFI_TPL
146 EFIAPI
147 EfiGetCurrentTpl (
148 VOID
149 );
150
151 /**
152 This function initializes a basic mutual exclusion lock to the released state
153 and returns the lock. Each lock provides mutual exclusion access at its task
154 priority level. Since there is no preemption or multiprocessor support in EFI,
155 acquiring the lock only consists of raising to the locks TPL.
156
157 @param Lock A pointer to the lock data structure to initialize.
158 @param Priority EFI TPL associated with the lock.
159
160 @return The lock.
161
162 **/
163 EFI_LOCK *
164 EFIAPI
165 EfiInitializeLock (
166 IN OUT EFI_LOCK *Lock,
167 IN EFI_TPL Priority
168 );
169
170 /**
171 This macro initializes the contents of a basic mutual exclusion lock to the
172 released state. Each lock provides mutual exclusion access at its task
173 priority level. Since there is no preemption or multiprocessor support in EFI,
174 acquiring the lock only consists of raising to the locks TPL.
175
176 @param Lock A pointer to the lock data structure to initialize.
177 @param Priority The task priority level of the lock.
178
179 @return The lock.
180
181 **/
182 #define EFI_INITIALIZE_LOCK_VARIABLE(Priority) \
183 {Priority, EFI_TPL_APPLICATION, EfiLockReleased }
184
185
186 /**
187
188 Macro that calls DebugAssert() if an EFI_LOCK structure is not in the locked state.
189
190 If the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set,
191 then this macro evaluates the EFI_LOCK structure specified by Lock. If Lock
192 is not in the locked state, then DebugAssert() is called passing in the source
193 filename, source line number, and Lock.
194
195 If Lock is NULL, then ASSERT().
196
197 @param LockParameter A pointer to the lock to acquire.
198
199 **/
200 #define ASSERT_LOCKED(LockParameter) \
201 do { \
202 if (DebugAssertEnabled ()) { \
203 ASSERT (LockParameter != NULL); \
204 if ((LockParameter)->Lock != EfiLockAcquired) { \
205 _ASSERT (LockParameter not locked); \
206 } \
207 } \
208 } while (FALSE)
209
210
211 /**
212 This function raises the system's current task priority level to the task
213 priority level of the mutual exclusion lock. Then, it places the lock in the
214 acquired state.
215
216 @param Priority The task priority level of the lock.
217
218 **/
219 VOID
220 EFIAPI
221 EfiAcquireLock (
222 IN EFI_LOCK *Lock
223 );
224
225 /**
226 This function raises the system's current task priority level to the task
227 priority level of the mutual exclusion lock. Then, it attempts to place the
228 lock in the acquired state.
229
230 @param Lock A pointer to the lock to acquire.
231
232 @retval EFI_SUCCESS The lock was acquired.
233 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
234
235 **/
236 EFI_STATUS
237 EFIAPI
238 EfiAcquireLockOrFail (
239 IN EFI_LOCK *Lock
240 );
241
242 /**
243 This function transitions a mutual exclusion lock from the acquired state to
244 the released state, and restores the system's task priority level to its
245 previous level.
246
247 @param Lock A pointer to the lock to release.
248
249 **/
250 VOID
251 EFIAPI
252 EfiReleaseLock (
253 IN EFI_LOCK *Lock
254 );
255
256 /**
257 Tests whether a controller is managed by a specific driver.
258
259 This function tests whether a specific driver manages ControllerHandle by
260 opening on DriverBindingHandle a protocol specified by ProtocolGuid with
261 attribute EFI_OPEN_PROTOCOL_BY_DRIVER. This library function is used to
262 implement the Component Name Protocol for EFI Drivers.
263 If ProtocolGuid is NULL, then ASSERT().
264
265 @param ControllerHandle A handle for a controller to test.
266 @param DriverBindingHandle Specifies the driver binding handle for the
267 driver.
268 @param ProtocolGuid Supplies GUID for the protocol opened by the
269 driver on the controller.
270
271 @retval EFI_SUCCESS ControllerHandle is managed by the specific
272 driver.
273 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the specific
274 driver.
275
276 **/
277 EFI_STATUS
278 EFIAPI
279 EfiTestManagedDevice (
280 IN CONST EFI_HANDLE ControllerHandle,
281 IN CONST EFI_HANDLE DriverBindingHandle,
282 IN CONST EFI_GUID *ProtocolGuid
283 );
284
285 /**
286 Tests whether a child handle is a children device of the controller.
287
288 This function tests whether ChildHandle is one of the children of
289 ControllerHandle which are consuming a protocol specified by ProtocolGuid
290 with the attribute bit EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER set. This
291 library function is used to implement the Component Name Protocol for EFI
292 Drivers.
293 If ProtocolGuid is NULL, then ASSERT().
294
295 @param ControllerHandle A handle for a (parent) controller to test.
296 @param ChildHandle A child handle to test.
297 @param ConsumsedGuid Supplies GUID for the protocol consumed by
298 children from controller.
299
300 @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle.
301 @retval EFI_UNSUPPORTED ChildHandle is not a child of the
302 ControllerHandle.
303
304 **/
305 EFI_STATUS
306 EFIAPI
307 EfiTestChildHandle (
308 IN CONST EFI_HANDLE ControllerHandle,
309 IN CONST EFI_HANDLE ChildHandle,
310 IN CONST EFI_GUID *ProtocolGuid
311 );
312
313 /**
314 This function looks up a Unicode string in UnicodeStringTable. If Language is
315 a member of SupportedLanguages and a Unicode string is found in UnicodeStringTable
316 that matches the language code specified by Language, then it is returned in
317 UnicodeString.
318
319 @param Language A pointer to the ISO 639-2 language code for the
320 Unicode string to look up and return.
321 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
322 that the Unicode string table supports. Language
323 must be a member of this set.
324 @param UnicodeStringTable A pointer to the table of Unicode strings.
325 @param UnicodeString A pointer to the Unicode string from UnicodeStringTable
326 that matches the language specified by Language.
327
328 @retval EFI_SUCCESS The Unicode string that matches the language
329 specified by Language was found
330 in the table of Unicoide strings UnicodeStringTable,
331 and it was returned in UnicodeString.
332 @retval EFI_INVALID_PARAMETER Language is NULL.
333 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
334 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
335 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
336 @retval EFI_UNSUPPORTED The language specified by Language is not a
337 member of SupportedLanguages.
338 @retval EFI_UNSUPPORTED The language specified by Language is not
339 supported by UnicodeStringTable.
340
341 **/
342 EFI_STATUS
343 EFIAPI
344 LookupUnicodeString (
345 IN CONST CHAR8 *Language,
346 IN CONST CHAR8 *SupportedLanguages,
347 IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable,
348 OUT CHAR16 **UnicodeString
349 );
350
351 /**
352 This function adds a Unicode string to UnicodeStringTable.
353 If Language is a member of SupportedLanguages then UnicodeString is added to
354 UnicodeStringTable. New buffers are allocated for both Language and
355 UnicodeString. The contents of Language and UnicodeString are copied into
356 these new buffers. These buffers are automatically freed when
357 FreeUnicodeStringTable() is called.
358
359 @param Language A pointer to the ISO 639-2 language code for the Unicode
360 string to add.
361 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
362 that the Unicode string table supports.
363 Language must be a member of this set.
364 @param UnicodeStringTable A pointer to the table of Unicode strings.
365 @param UnicodeString A pointer to the Unicode string to add.
366
367 @retval EFI_SUCCESS The Unicode string that matches the language
368 specified by Language was found in the table of
369 Unicode strings UnicodeStringTable, and it was
370 returned in UnicodeString.
371 @retval EFI_INVALID_PARAMETER Language is NULL.
372 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
373 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
374 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
375 @retval EFI_ALREADY_STARTED A Unicode string with language Language is
376 already present in UnicodeStringTable.
377 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another
378 Unicode string to UnicodeStringTable.
379 @retval EFI_UNSUPPORTED The language specified by Language is not a
380 member of SupportedLanguages.
381
382 **/
383 EFI_STATUS
384 EFIAPI
385 AddUnicodeString (
386 IN CONST CHAR8 *Language,
387 IN CONST CHAR8 *SupportedLanguages,
388 IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable,
389 IN CONST CHAR16 *UnicodeString
390 );
391
392 /**
393 This function frees the table of Unicode strings in UnicodeStringTable.
394 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
395 Otherwise, each language code, and each Unicode string in the Unicode string
396 table are freed, and EFI_SUCCESS is returned.
397
398 @param UnicodeStringTable A pointer to the table of Unicode strings.
399
400 @retval EFI_SUCCESS The Unicode string table was freed.
401
402 **/
403 EFI_STATUS
404 EFIAPI
405 FreeUnicodeStringTable (
406 IN EFI_UNICODE_STRING_TABLE *UnicodeStringTable
407 );
408
409 /**
410 This function computes and returns the width of the Unicode character
411 specified by UnicodeChar.
412
413 @param UnicodeChar A Unicode character.
414
415 @retval 0 The width if UnicodeChar could not be determined.
416 @retval 1 UnicodeChar is a narrow glyph.
417 @retval 2 UnicodeChar is a wide glyph.
418
419 **/
420 UINTN
421 EFIAPI
422 GetGlyphWidth (
423 IN CHAR16 UnicodeChar
424 );
425
426 /**
427 This function computes and returns the display length of
428 the Null-terminated Unicode string specified by String.
429 If String is NULL, then 0 is returned.
430 If any of the widths of the Unicode characters in String
431 can not be determined, then 0 is returned.
432
433 @param String A pointer to a Null-terminated Unicode string.
434
435 @return The display length of the Null-terminated Unicode string specified by String.
436
437 **/
438 UINTN
439 EFIAPI
440 UnicodeStringDisplayLength (
441 IN CONST CHAR16 *String
442 );
443
444 //
445 // Functions that abstract early Framework contamination of UEFI.
446 //
447 /**
448 Signal a Ready to Boot Event.
449
450 Create a Ready to Boot Event. Signal it and close it. This causes other
451 events of the same event group to be signaled in other modules.
452
453 **/
454 VOID
455 EFIAPI
456 EfiSignalEventReadyToBoot (
457 VOID
458 );
459
460 /**
461 Signal a Legacy Boot Event.
462
463 Create a legacy Boot Event. Signal it and close it. This causes other
464 events of the same event group to be signaled in other modules.
465
466 **/
467 VOID
468 EFIAPI
469 EfiSignalEventLegacyBoot (
470 VOID
471 );
472
473 /**
474 Create a Legacy Boot Event.
475
476 Tiano extended the CreateEvent Type enum to add a legacy boot event type.
477 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
478 added and now it's possible to not voilate the UEFI specification by
479 declaring a GUID for the legacy boot event class. This library supports
480 the EDK/EFI 1.10 form and EDK II/UEFI 2.0 form and allows common code to
481 work both ways.
482
483 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
484
485 @retval EFI_SUCCESS Event was created.
486 @retval Other Event was not created.
487
488 **/
489 EFI_STATUS
490 EFIAPI
491 EfiCreateEventLegacyBoot (
492 OUT EFI_EVENT *LegacyBootEvent
493 );
494
495 /**
496 Create an EFI event in the Legacy Boot Event Group and allows
497 the caller to specify a notification function.
498
499 This function abstracts the creation of the Legacy Boot Event.
500 The Framework moved from a proprietary to UEFI 2.0 based mechanism.
501 This library abstracts the caller from how this event is created to prevent
502 to code form having to change with the version of the specification supported.
503 If LegacyBootEvent is NULL, then ASSERT().
504
505 @param NotifyTpl The task priority level of the event.
506 @param NotifyFunction The notification function to call when the event is signaled.
507 @param NotifyContext The content to pass to NotifyFunction when the event is signaled.
508 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
509
510 @retval EFI_SUCCESS Event was created.
511 @retval Other Event was not created.
512
513 **/
514 EFI_STATUS
515 EFIAPI
516 EfiCreateEventLegacyBootEx (
517 IN EFI_TPL NotifyTpl,
518 IN EFI_EVENT_NOTIFY NotifyFunction, OPTIONAL
519 IN VOID *NotifyContext, OPTIONAL
520 OUT EFI_EVENT *LegacyBootEvent
521 );
522
523 /**
524 Create a Read to Boot Event.
525
526 Tiano extended the CreateEvent Type enum to add a ready to boot event type.
527 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
528 added and now it's possible to not voilate the UEFI specification and use
529 the ready to boot event class defined in UEFI 2.0. This library supports
530 the EDK/EFI 1.10 form and EDKII/UEFI 2.0 form and allows common code to
531 work both ways.
532
533 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
534
535 @retval EFI_SUCCESS Event was created.
536 @retval Other Event was not created.
537
538 **/
539 EFI_STATUS
540 EFIAPI
541 EfiCreateEventReadyToBoot (
542 OUT EFI_EVENT *ReadyToBootEvent
543 );
544
545 /**
546 Create an EFI event in the Ready To Boot Event Group and allows
547 the caller to specify a notification function.
548
549 This function abstracts the creation of the Ready to Boot Event.
550 The Framework moved from a proprietary to UEFI 2.0 based mechanism.
551 This library abstracts the caller from how this event is created to prevent
552 to code form having to change with the version of the specification supported.
553 If ReadyToBootEvent is NULL, then ASSERT().
554
555 @param NotifyTpl The task priority level of the event.
556 @param NotifyFunction The notification function to call when the event is signaled.
557 @param NotifyContext The content to pass to NotifyFunction when the event is signaled.
558 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
559
560 @retval EFI_SUCCESS Event was created.
561 @retval Other Event was not created.
562
563 **/
564 EFI_STATUS
565 EFIAPI
566 EfiCreateEventReadyToBootEx (
567 IN EFI_TPL NotifyTpl,
568 IN EFI_EVENT_NOTIFY NotifyFunction, OPTIONAL
569 IN VOID *NotifyContext, OPTIONAL
570 OUT EFI_EVENT *ReadyToBootEvent
571 );
572
573 /**
574 Initialize a Firmware Volume (FV) Media Device Path node.
575
576 Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
577 so as we move to UEFI 2.0 support we must use a mechanism that conforms with
578 the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
579 device path is defined for Tiano extensions of device path. If the code
580 is compiled to conform with the UEFI 2.0 specification use the new device path
581 else use the old form for backwards compatability.
582
583 @param FvDevicePathNode Pointer to a FV device path node to initialize
584 @param NameGuid FV file name to use in FvDevicePathNode
585
586 **/
587 VOID
588 EFIAPI
589 EfiInitializeFwVolDevicepathNode (
590 IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode,
591 IN CONST EFI_GUID *NameGuid
592 );
593
594 /**
595 Check to see if the Firmware Volume (FV) Media Device Path is valid
596
597 Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
598 so as we move to UEFI 2.0 support we must use a mechanism that conforms with
599 the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
600 device path is defined for Tiano extensions of device path. If the code
601 is compiled to conform with the UEFI 2.0 specification use the new device path
602 else use the old form for backwards compatability. The return value to this
603 function points to a location in FvDevicePathNode and it does not allocate
604 new memory for the GUID pointer that is returned.
605
606 @param FvDevicePathNode Pointer to FV device path to check.
607
608 @retval NULL FvDevicePathNode is not valid.
609 @retval Other FvDevicePathNode is valid and pointer to NameGuid was returned.
610
611 **/
612 EFI_GUID *
613 EFIAPI
614 EfiGetNameGuidFromFwVolDevicePathNode (
615 IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode
616 );
617
618 #endif