3 Copyright (c) 2004 - 2006, Intel Corporation. All rights reserved.<BR>
4 This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 Public header file for UEFI Lib
23 #ifndef __EDKII_GLUE_UEFI_LIB_H__
24 #define __EDKII_GLUE_UEFI_LIB_H__
27 #define EfiInitializeLock(_LOCK, _PRIORITY) GlueEfiInitializeLock(_LOCK, _PRIORITY)
28 #define EfiAcquireLock(_LOCK) GlueEfiAcquireLock(_LOCK)
29 #define EfiAcquireLockOrFail(_LOCK) GlueEfiAcquireLockOrFail(_LOCK)
30 #define EfiReleaseLock(_LOCK) GlueEfiReleaseLock(_LOCK)
31 #define GetGlyphWidth(_UNICODECHAR) GlueGetGlyphWidth(_UNICODECHAR)
32 #define EfiCreateEventLegacyBoot(_LEGACYBOOT) GlueEfiCreateEventLegacyBoot(_LEGACYBOOT)
33 #define EfiCreateEventReadyToBoot(_READYTOBOOTEVENT) GlueEfiCreateEventReadyToBoot(_READYTOBOOTEVENT)
34 #define EfiGetNameGuidFromFwVolDevicePathNode(_FVDEVICEPATHNODE) GlueEfiGetNameGuidFromFwVolDevicePathNode(_FVDEVICEPATHNODE)
35 #define EfiInitializeFwVolDevicepathNode(_FVDEVICEPATHNODE, _NAMEGUID) GlueEfiInitializeFwVolDevicepathNode(_FVDEVICEPATHNODE, _NAMEGUID)
42 EfiLockUninitialized
= 0,
49 This function searches the list of configuration tables stored in the EFI System
50 Table for a table with a GUID that matches TableGuid. If a match is found,
51 then a pointer to the configuration table is returned in Table, and EFI_SUCCESS
52 is returned. If a matching GUID is not found, then EFI_NOT_FOUND is returned.
54 @param TableGuid Pointer to table's GUID type..
55 @param Table Pointer to the table associated with TableGuid in the EFI System Table.
57 @retval EFI_SUCCESS A configuration table matching TableGuid was found.
58 @retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found.
63 EfiGetSystemConfigurationTable (
64 IN EFI_GUID
*TableGuid
,
69 This function causes the notification function to be executed for every protocol
70 of type ProtocolGuid instance that exists in the system when this function is
71 invoked. In addition, every time a protocol of type ProtocolGuid instance is
72 installed or reinstalled, the notification function is also executed.
74 @param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired.
75 @param NotifyTpl Supplies the task priority level of the event notifications.
76 @param NotifyFunction Supplies the function to notify when the event is signaled.
77 @param NotifyContext The context parameter to pass to NotifyFunction.
78 @param Registration A pointer to a memory location to receive the registration value.
80 @return The notification event that was created.
85 EfiCreateProtocolNotifyEvent(
86 IN EFI_GUID
*ProtocolGuid
,
88 IN EFI_EVENT_NOTIFY NotifyFunction
,
89 IN VOID
*NotifyContext
, OPTIONAL
90 OUT VOID
**Registration
94 This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
95 This event is signaled with EfiNamedEventSignal(). This provide the ability for
96 one or more listeners on the same event named by the GUID specified by Name.
98 @param Name Supplies GUID name of the event.
99 @param NotifyTpl Supplies the task priority level of the event notifications.
100 @param NotifyFunction Supplies the function to notify when the event is signaled.
101 @param NotifyContext The context parameter to pass to NotifyFunction.
102 @param Registration A pointer to a memory location to receive the registration value.
104 @retval EFI_SUCCESS A named event was created.
105 @retval EFI_OUT_OF_RESOURCES There are not enough resource to create the named event.
110 EfiNamedEventListen (
111 IN CONST EFI_GUID
*Name
,
112 IN EFI_TPL NotifyTpl
,
113 IN EFI_EVENT_NOTIFY NotifyFunction
,
114 IN CONST VOID
*NotifyContext
, OPTIONAL
115 OUT VOID
*Registration OPTIONAL
119 This function signals the named event specified by Name. The named event must
120 have been created with EfiNamedEventListen().
122 @param Name Supplies GUID name of the event.
124 @retval EFI_SUCCESS A named event was signaled.
125 @retval EFI_OUT_OF_RESOURCES There are not enough resource to signal the named event.
130 EfiNamedEventSignal (
131 IN CONST EFI_GUID
*Name
135 Returns the current TPL.
137 This function returns the current TPL. There is no EFI service to directly
138 retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
139 the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level
140 can then immediately be restored back to the current TPL level with a call
145 @retvale EFI_TPL The current TPL.
155 This function initializes a basic mutual exclusion lock to the released state
156 and returns the lock. Each lock provides mutual exclusion access at its task
157 priority level. Since there is no preemption or multiprocessor support in EFI,
158 acquiring the lock only consists of raising to the locks TPL.
160 @param Lock A pointer to the lock data structure to initialize.
161 @param Priority EFI TPL associated with the lock.
168 GlueEfiInitializeLock (
169 IN OUT EFI_LOCK
*Lock
,
174 This macro initializes the contents of a basic mutual exclusion lock to the
175 released state. Each lock provides mutual exclusion access at its task
176 priority level. Since there is no preemption or multiprocessor support in EFI,
177 acquiring the lock only consists of raising to the locks TPL.
179 @param Lock A pointer to the lock data structure to initialize.
180 @param Priority The task priority level of the lock.
185 #ifdef EFI_INITIALIZE_LOCK_VARIABLE
186 #undef EFI_INITIALIZE_LOCK_VARIABLE
189 #define EFI_INITIALIZE_LOCK_VARIABLE(Priority) \
190 {Priority, EFI_TPL_APPLICATION, EfiLockReleased }
195 Macro that calls DebugAssert() if an EFI_LOCK structure is not in the locked state.
197 If the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set,
198 then this macro evaluates the EFI_LOCK structure specified by Lock. If Lock
199 is not in the locked state, then DebugAssert() is called passing in the source
200 filename, source line number, and Lock.
202 If Lock is NULL, then ASSERT().
204 @param LockParameter A pointer to the lock to acquire.
211 #define ASSERT_LOCKED(LockParameter) \
213 if (DebugAssertEnabled ()) { \
214 ASSERT (LockParameter != NULL); \
215 if ((LockParameter)->Lock != EfiLockAcquired) { \
216 _ASSERT (LockParameter not locked); \
223 This function raises the system's current task priority level to the task
224 priority level of the mutual exclusion lock. Then, it places the lock in the
227 @param Priority The task priority level of the lock.
237 This function raises the system's current task priority level to the task
238 priority level of the mutual exclusion lock. Then, it attempts to place the
239 lock in the acquired state.
241 @param Lock A pointer to the lock to acquire.
243 @retval EFI_SUCCESS The lock was acquired.
244 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
249 GlueEfiAcquireLockOrFail (
254 This function transitions a mutual exclusion lock from the acquired state to
255 the released state, and restores the system's task priority level to its
258 @param Lock A pointer to the lock to release.
268 Tests whether a controller handle is being managed by a specific driver.
270 This function tests whether the driver specified by DriverBindingHandle is
271 currently managing the controller specified by ControllerHandle. This test
272 is performed by evaluating if the the protocol specified by ProtocolGuid is
273 present on ControllerHandle and is was opened by DriverBindingHandle with an
274 attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
275 If ProtocolGuid is NULL, then ASSERT().
277 @param ControllerHandle A handle for a controller to test.
278 @param DriverBindingHandle Specifies the driver binding handle for the
280 @param ProtocolGuid Specifies the protocol that the driver specified
281 by DriverBindingHandle opens in its Start()
284 @retval EFI_SUCCESS ControllerHandle is managed by the driver
285 specifed by DriverBindingHandle.
286 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the driver
287 specifed by DriverBindingHandle.
292 EfiTestManagedDevice (
293 IN CONST EFI_HANDLE ControllerHandle
,
294 IN CONST EFI_HANDLE DriverBindingHandle
,
295 IN CONST EFI_GUID
*ProtocolGuid
299 Tests whether a child handle is a child device of the controller.
301 This function tests whether ChildHandle is one of the children of
302 ControllerHandle. This test is performed by checking to see if the protocol
303 specified by ProtocolGuid is present on ControllerHandle and opened by
304 ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
305 If ProtocolGuid is NULL, then ASSERT().
307 @param ControllerHandle A handle for a (parent) controller to test.
308 @param ChildHandle A child handle to test.
309 @param ConsumsedGuid Supplies the protocol that the child controller
310 opens on its parent controller.
312 @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle.
313 @retval EFI_UNSUPPORTED ChildHandle is not a child of the
320 IN CONST EFI_HANDLE ControllerHandle
,
321 IN CONST EFI_HANDLE ChildHandle
,
322 IN CONST EFI_GUID
*ProtocolGuid
326 This function looks up a Unicode string in UnicodeStringTable. If Language is
327 a member of SupportedLanguages and a Unicode string is found in UnicodeStringTable
328 that matches the language code specified by Language, then it is returned in
331 @param Language A pointer to the ISO 639-2 language code for the
332 Unicode string to look up and return.
333 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
334 that the Unicode string table supports. Language
335 must be a member of this set.
336 @param UnicodeStringTable A pointer to the table of Unicode strings.
337 @param UnicodeString A pointer to the Unicode string from UnicodeStringTable
338 that matches the language specified by Language.
340 @retval EFI_SUCCESS The Unicode string that matches the language
341 specified by Language was found
342 in the table of Unicoide strings UnicodeStringTable,
343 and it was returned in UnicodeString.
344 @retval EFI_INVALID_PARAMETER Language is NULL.
345 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
346 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
347 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
348 @retval EFI_UNSUPPORTED The language specified by Language is not a
349 member of SupportedLanguages.
350 @retval EFI_UNSUPPORTED The language specified by Language is not
351 supported by UnicodeStringTable.
356 LookupUnicodeString (
357 IN CONST CHAR8
*Language
,
358 IN CONST CHAR8
*SupportedLanguages
,
359 IN CONST EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
,
360 OUT CHAR16
**UnicodeString
364 This function adds a Unicode string to UnicodeStringTable.
365 If Language is a member of SupportedLanguages then UnicodeString is added to
366 UnicodeStringTable. New buffers are allocated for both Language and
367 UnicodeString. The contents of Language and UnicodeString are copied into
368 these new buffers. These buffers are automatically freed when
369 FreeUnicodeStringTable() is called.
371 @param Language A pointer to the ISO 639-2 language code for the Unicode
373 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
374 that the Unicode string table supports.
375 Language must be a member of this set.
376 @param UnicodeStringTable A pointer to the table of Unicode strings.
377 @param UnicodeString A pointer to the Unicode string to add.
379 @retval EFI_SUCCESS The Unicode string that matches the language
380 specified by Language was found in the table of
381 Unicode strings UnicodeStringTable, and it was
382 returned in UnicodeString.
383 @retval EFI_INVALID_PARAMETER Language is NULL.
384 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
385 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
386 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
387 @retval EFI_ALREADY_STARTED A Unicode string with language Language is
388 already present in UnicodeStringTable.
389 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another
390 Unicode string to UnicodeStringTable.
391 @retval EFI_UNSUPPORTED The language specified by Language is not a
392 member of SupportedLanguages.
398 IN CONST CHAR8
*Language
,
399 IN CONST CHAR8
*SupportedLanguages
,
400 IN EFI_UNICODE_STRING_TABLE
**UnicodeStringTable
,
401 IN CONST CHAR16
*UnicodeString
405 This function frees the table of Unicode strings in UnicodeStringTable.
406 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
407 Otherwise, each language code, and each Unicode string in the Unicode string
408 table are freed, and EFI_SUCCESS is returned.
410 @param UnicodeStringTable A pointer to the table of Unicode strings.
412 @retval EFI_SUCCESS The Unicode string table was freed.
417 FreeUnicodeStringTable (
418 IN EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
422 This function computes and returns the width of the Unicode character
423 specified by UnicodeChar.
425 @param UnicodeChar A Unicode character.
427 @retval 0 The width if UnicodeChar could not be determined.
428 @retval 1 UnicodeChar is a narrow glyph.
429 @retval 2 UnicodeChar is a wide glyph.
435 IN CHAR16 UnicodeChar
439 This function computes and returns the display length of
440 the Null-terminated Unicode string specified by String.
441 If String is NULL, then 0 is returned.
442 If any of the widths of the Unicode characters in String
443 can not be determined, then 0 is returned.
445 @param String A pointer to a Null-terminated Unicode string.
447 @return The display length of the Null-terminated Unicode string specified by String.
452 UnicodeStringDisplayLength (
453 IN CONST CHAR16
*String
457 // Functions that abstract early Framework contamination of UEFI.
460 Signal a Ready to Boot Event.
462 Create a Ready to Boot Event. Signal it and close it. This causes other
463 events of the same event group to be signaled in other modules.
468 EfiSignalEventReadyToBoot (
473 Signal a Legacy Boot Event.
475 Create a legacy Boot Event. Signal it and close it. This causes other
476 events of the same event group to be signaled in other modules.
481 EfiSignalEventLegacyBoot (
486 Create a Legacy Boot Event.
488 Tiano extended the CreateEvent Type enum to add a legacy boot event type.
489 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
490 added and now it's possible to not voilate the UEFI specification by
491 declaring a GUID for the legacy boot event class. This library supports
492 the EDK/EFI 1.10 form and EDK II/UEFI 2.0 form and allows common code to
495 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
497 @retval EFI_SUCCESS Event was created.
498 @retval Other Event was not created.
503 GlueEfiCreateEventLegacyBoot (
504 OUT EFI_EVENT
*LegacyBootEvent
508 Create an EFI event in the Legacy Boot Event Group and allows
509 the caller to specify a notification function.
511 This function abstracts the creation of the Legacy Boot Event.
512 The Framework moved from a proprietary to UEFI 2.0 based mechanism.
513 This library abstracts the caller from how this event is created to prevent
514 to code form having to change with the version of the specification supported.
515 If LegacyBootEvent is NULL, then ASSERT().
517 @param NotifyTpl The task priority level of the event.
518 @param NotifyFunction The notification function to call when the event is signaled.
519 @param NotifyContext The content to pass to NotifyFunction when the event is signaled.
520 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
522 @retval EFI_SUCCESS Event was created.
523 @retval Other Event was not created.
528 EfiCreateEventLegacyBootEx (
529 IN EFI_TPL NotifyTpl
,
530 IN EFI_EVENT_NOTIFY NotifyFunction
, OPTIONAL
531 IN VOID
*NotifyContext
, OPTIONAL
532 OUT EFI_EVENT
*LegacyBootEvent
536 Create a Read to Boot Event.
538 Tiano extended the CreateEvent Type enum to add a ready to boot event type.
539 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
540 added and now it's possible to not voilate the UEFI specification and use
541 the ready to boot event class defined in UEFI 2.0. This library supports
542 the EDK/EFI 1.10 form and EDKII/UEFI 2.0 form and allows common code to
545 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
547 @retval EFI_SUCCESS Event was created.
548 @retval Other Event was not created.
553 GlueEfiCreateEventReadyToBoot (
554 OUT EFI_EVENT
*ReadyToBootEvent
558 Create an EFI event in the Ready To Boot Event Group and allows
559 the caller to specify a notification function.
561 This function abstracts the creation of the Ready to Boot Event.
562 The Framework moved from a proprietary to UEFI 2.0 based mechanism.
563 This library abstracts the caller from how this event is created to prevent
564 to code form having to change with the version of the specification supported.
565 If ReadyToBootEvent is NULL, then ASSERT().
567 @param NotifyTpl The task priority level of the event.
568 @param NotifyFunction The notification function to call when the event is signaled.
569 @param NotifyContext The content to pass to NotifyFunction when the event is signaled.
570 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).
572 @retval EFI_SUCCESS Event was created.
573 @retval Other Event was not created.
578 EfiCreateEventReadyToBootEx (
579 IN EFI_TPL NotifyTpl
,
580 IN EFI_EVENT_NOTIFY NotifyFunction
, OPTIONAL
581 IN VOID
*NotifyContext
, OPTIONAL
582 OUT EFI_EVENT
*ReadyToBootEvent
586 Initialize a Firmware Volume (FV) Media Device Path node.
588 Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
589 so as we move to UEFI 2.0 support we must use a mechanism that conforms with
590 the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
591 device path is defined for Tiano extensions of device path. If the code
592 is compiled to conform with the UEFI 2.0 specification use the new device path
593 else use the old form for backwards compatability.
595 @param FvDevicePathNode Pointer to a FV device path node to initialize
596 @param NameGuid FV file name to use in FvDevicePathNode
601 GlueEfiInitializeFwVolDevicepathNode (
602 IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH
*FvDevicePathNode
,
603 IN CONST EFI_GUID
*NameGuid
607 Check to see if the Firmware Volume (FV) Media Device Path is valid
609 Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
610 so as we move to UEFI 2.0 support we must use a mechanism that conforms with
611 the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
612 device path is defined for Tiano extensions of device path. If the code
613 is compiled to conform with the UEFI 2.0 specification use the new device path
614 else use the old form for backwards compatability. The return value to this
615 function points to a location in FvDevicePathNode and it does not allocate
616 new memory for the GUID pointer that is returned.
618 @param FvDevicePathNode Pointer to FV device path to check.
620 @retval NULL FvDevicePathNode is not valid.
621 @retval Other FvDevicePathNode is valid and pointer to NameGuid was returned.
626 GlueEfiGetNameGuidFromFwVolDevicePathNode (
627 IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH
*FvDevicePathNode
631 Prints a formatted Unicode string to the console output device specified by
632 ConOut defined in the EFI_SYSTEM_TABLE.
634 This function prints a formatted Unicode string to the console output device
635 specified by ConOut in EFI_SYSTEM_TABLE and returns the number of Unicode
636 characters that printed to ConOut. If the length of the formatted Unicode
637 string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
638 PcdUefiLibMaxPrintBufferSize characters are sent to ConOut.
640 @param Format Null-terminated Unicode format string.
641 @param ... VARARG list consumed to process Format.
642 If Format is NULL, then ASSERT().
643 If Format is not aligned on a 16-bit boundary, then ASSERT().
649 IN CONST CHAR16
*Format
,
654 Prints a formatted Unicode string to the console output device specified by
655 StdErr defined in the EFI_SYSTEM_TABLE.
657 This function prints a formatted Unicode string to the console output device
658 specified by StdErr in EFI_SYSTEM_TABLE and returns the number of Unicode
659 characters that printed to StdErr. If the length of the formatted Unicode
660 string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
661 PcdUefiLibMaxPrintBufferSize characters are sent to StdErr.
663 @param Format Null-terminated Unicode format string.
664 @param ... VARARG list consumed to process Format.
665 If Format is NULL, then ASSERT().
666 If Format is not aligned on a 16-bit boundary, then ASSERT().
672 IN CONST CHAR16
*Format
,
677 Prints a formatted ASCII string to the console output device specified by
678 ConOut defined in the EFI_SYSTEM_TABLE.
680 This function prints a formatted ASCII string to the console output device
681 specified by ConOut in EFI_SYSTEM_TABLE and returns the number of ASCII
682 characters that printed to ConOut. If the length of the formatted ASCII
683 string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
684 PcdUefiLibMaxPrintBufferSize characters are sent to ConOut.
686 @param Format Null-terminated ASCII format string.
687 @param ... VARARG list consumed to process Format.
688 If Format is NULL, then ASSERT().
689 If Format is not aligned on a 16-bit boundary, then ASSERT().
695 IN CONST CHAR8
*Format
,
700 Prints a formatted ASCII string to the console output device specified by
701 StdErr defined in the EFI_SYSTEM_TABLE.
703 This function prints a formatted ASCII string to the console output device
704 specified by StdErr in EFI_SYSTEM_TABLE and returns the number of ASCII
705 characters that printed to StdErr. If the length of the formatted ASCII
706 string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
707 PcdUefiLibMaxPrintBufferSize characters are sent to StdErr.
709 @param Format Null-terminated ASCII format string.
710 @param ... VARARG list consumed to process Format.
711 If Format is NULL, then ASSERT().
712 If Format is not aligned on a 16-bit boundary, then ASSERT().
718 IN CONST CHAR8
*Format
,