1 /** @file 2 Provides library functions for common UEFI operations. Only available to DXE 3 and UEFI module types. 4 5 The UEFI Library provides functions and macros that simplify the development of 6 UEFI Drivers and UEFI Applications. These functions and macros help manage EFI 7 events, build simple locks utilizing EFI Task Priority Levels (TPLs), install 8 EFI Driver Model related protocols, manage Unicode string tables for UEFI Drivers, 9 and print messages on the console output and standard error devices. 10 11 Note that a reserved macro named MDEPKG_NDEBUG is introduced for the intention 12 of size reduction when compiler optimization is disabled. If MDEPKG_NDEBUG is 13 defined, then debug and assert related macros wrapped by it are the NULL implementations. 14 15 Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> 16 This program and the accompanying materials are licensed and made available under 17 the terms and conditions of the BSD License that accompanies this distribution. 18 The full text of the license may be found at 19 http://opensource.org/licenses/bsd-license.php. 20 21 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 22 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 23 24 **/ 25 26 #ifndef __UEFI_LIB_H__ 27 #define __UEFI_LIB_H__ 28 29 #include <Protocol/DriverBinding.h> 30 #include <Protocol/DriverConfiguration.h> 31 #include <Protocol/ComponentName.h> 32 #include <Protocol/ComponentName2.h> 33 #include <Protocol/DriverDiagnostics.h> 34 #include <Protocol/DriverDiagnostics2.h> 35 #include <Protocol/GraphicsOutput.h> 36 37 #include <Library/BaseLib.h> 38 39 /// 40 /// Unicode String Table 41 /// 42 typedef struct { 43 CHAR8 *Language; 44 CHAR16 *UnicodeString; 45 } EFI_UNICODE_STRING_TABLE; 46 47 /// 48 /// EFI Lock Status 49 /// 50 typedef enum { 51 EfiLockUninitialized = 0, 52 EfiLockReleased = 1, 53 EfiLockAcquired = 2 54 } EFI_LOCK_STATE; 55 56 /// 57 /// EFI Lock 58 /// 59 typedef struct { 60 EFI_TPL Tpl; 61 EFI_TPL OwnerTpl; 62 EFI_LOCK_STATE Lock; 63 } EFI_LOCK; 64 65 /** 66 Macro that returns the number of 100 ns units for a specified number of microseconds. 67 This is useful for managing EFI timer events. 68 69 @param Microseconds The number of microseconds. 70 71 @return The number of 100 ns units equivalent to the number of microseconds specified 72 by Microseconds. 73 74 **/ 75 #define EFI_TIMER_PERIOD_MICROSECONDS(Microseconds) MultU64x32((UINT64)(Microseconds), 10) 76 77 /** 78 Macro that returns the number of 100 ns units for a specified number of milliseconds. 79 This is useful for managing EFI timer events. 80 81 @param Milliseconds The number of milliseconds. 82 83 @return The number of 100 ns units equivalent to the number of milliseconds specified 84 by Milliseconds. 85 86 **/ 87 #define EFI_TIMER_PERIOD_MILLISECONDS(Milliseconds) MultU64x32((UINT64)(Milliseconds), 10000) 88 89 /** 90 Macro that returns the number of 100 ns units for a specified number of seconds. 91 This is useful for managing EFI timer events. 92 93 @param Seconds The number of seconds. 94 95 @return The number of 100 ns units equivalent to the number of seconds specified 96 by Seconds. 97 98 **/ 99 #define EFI_TIMER_PERIOD_SECONDS(Seconds) MultU64x32((UINT64)(Seconds), 10000000) 100 101 /** 102 Macro that returns the a pointer to the next EFI_MEMORY_DESCRIPTOR in an array 103 returned from GetMemoryMap(). 104 105 @param MemoryDescriptor A pointer to an EFI_MEMORY_DESCRIPTOR. 106 107 @param Size The size, in bytes, of the current EFI_MEMORY_DESCRIPTOR. 108 109 @return A pointer to the next EFI_MEMORY_DESCRIPTOR. 110 111 **/ 112 #define NEXT_MEMORY_DESCRIPTOR(MemoryDescriptor, Size) \ 113 ((EFI_MEMORY_DESCRIPTOR *)((UINT8 *)(MemoryDescriptor) + (Size))) 114 115 /** 116 Retrieves a pointer to the system configuration table from the EFI System Table 117 based on a specified GUID. 118 119 This function searches the list of configuration tables stored in the EFI System Table 120 for a table with a GUID that matches TableGuid. If a match is found, then a pointer to 121 the configuration table is returned in Table, and EFI_SUCCESS is returned. If a matching GUID 122 is not found, then EFI_NOT_FOUND is returned. 123 If TableGuid is NULL, then ASSERT(). 124 If Table is NULL, then ASSERT(). 125 126 @param TableGuid The pointer to table's GUID type.. 127 @param Table The pointer to the table associated with TableGuid in the EFI System Table. 128 129 @retval EFI_SUCCESS A configuration table matching TableGuid was found. 130 @retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found. 131 132 **/ 133 EFI_STATUS 134 EFIAPI 135 EfiGetSystemConfigurationTable ( 136 IN EFI_GUID *TableGuid, 137 OUT VOID **Table 138 ); 139 140 /** 141 Creates and returns a notification event and registers that event with all the protocol 142 instances specified by ProtocolGuid. 143 144 This function causes the notification function to be executed for every protocol of type 145 ProtocolGuid instance that exists in the system when this function is invoked. If there are 146 no instances of ProtocolGuid in the handle database at the time this function is invoked, 147 then the notification function is still executed one time. In addition, every time a protocol 148 of type ProtocolGuid instance is installed or reinstalled, the notification function is also 149 executed. This function returns the notification event that was created. 150 If ProtocolGuid is NULL, then ASSERT(). 151 If NotifyTpl is not a legal TPL value, then ASSERT(). 152 If NotifyFunction is NULL, then ASSERT(). 153 If Registration is NULL, then ASSERT(). 154 155 156 @param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired. 157 @param NotifyTpl Supplies the task priority level of the event notifications. 158 @param NotifyFunction Supplies the function to notify when the event is signaled. 159 @param NotifyContext The context parameter to pass to NotifyFunction. 160 @param Registration A pointer to a memory location to receive the registration value. 161 This value is passed to LocateHandle() to obtain new handles that 162 have been added that support the ProtocolGuid-specified protocol. 163 164 @return The notification event that was created. 165 166 **/ 167 EFI_EVENT 168 EFIAPI 169 EfiCreateProtocolNotifyEvent( 170 IN EFI_GUID *ProtocolGuid, 171 IN EFI_TPL NotifyTpl, 172 IN EFI_EVENT_NOTIFY NotifyFunction, 173 IN VOID *NotifyContext, OPTIONAL 174 OUT VOID **Registration 175 ); 176 177 /** 178 Creates a named event that can be signaled with EfiNamedEventSignal(). 179 180 This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext. 181 This event is signaled with EfiNamedEventSignal(). This provides the ability for one or more 182 listeners on the same event named by the GUID specified by Name. 183 If Name is NULL, then ASSERT(). 184 If NotifyTpl is not a legal TPL value, then ASSERT(). 185 If NotifyFunction is NULL, then ASSERT(). 186 187 @param Name Supplies GUID name of the event. 188 @param NotifyTpl Supplies the task priority level of the event notifications. 189 @param NotifyFunction Supplies the function to notify when the event is signaled. 190 @param NotifyContext The context parameter to pass to NotifyFunction. 191 @param Registration A pointer to a memory location to receive the registration value. 192 193 @retval EFI_SUCCESS A named event was created. 194 @retval EFI_OUT_OF_RESOURCES There are not enough resources to create the named event. 195 196 **/ 197 EFI_STATUS 198 EFIAPI 199 EfiNamedEventListen ( 200 IN CONST EFI_GUID *Name, 201 IN EFI_TPL NotifyTpl, 202 IN EFI_EVENT_NOTIFY NotifyFunction, 203 IN CONST VOID *NotifyContext, OPTIONAL 204 OUT VOID *Registration OPTIONAL 205 ); 206 207 /** 208 Signals a named event created with EfiNamedEventListen(). 209 210 This function signals the named event specified by Name. The named event must have been 211 created with EfiNamedEventListen(). 212 If Name is NULL, then ASSERT(). 213 214 @param Name Supplies the GUID name of the event. 215 216 @retval EFI_SUCCESS A named event was signaled. 217 @retval EFI_OUT_OF_RESOURCES There are not enough resources to signal the named event. 218 219 **/ 220 EFI_STATUS 221 EFIAPI 222 EfiNamedEventSignal ( 223 IN CONST EFI_GUID *Name 224 ); 225 226 /** 227 Signals an event group by placing a new event in the group temporarily and 228 signaling it. 229 230 @param[in] EventGroup Supplies the unique identifier of the event 231 group to signal. 232 233 @retval EFI_SUCCESS The event group was signaled successfully. 234 @retval EFI_INVALID_PARAMETER EventGroup is NULL. 235 @return Error codes that report problems about event 236 creation or signaling. 237 **/ 238 EFI_STATUS 239 EFIAPI 240 EfiEventGroupSignal ( 241 IN CONST EFI_GUID *EventGroup 242 ); 243 244 /** 245 Returns the current TPL. 246 247 This function returns the current TPL. There is no EFI service to directly 248 retrieve the current TPL. Instead, the RaiseTPL() function is used to raise 249 the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level 250 can then immediately be restored back to the current TPL level with a call 251 to RestoreTPL(). 252 253 @return The current TPL. 254 255 **/ 256 EFI_TPL 257 EFIAPI 258 EfiGetCurrentTpl ( 259 VOID 260 ); 261 262 /** 263 Initializes a basic mutual exclusion lock. 264 265 This function initializes a basic mutual exclusion lock to the released state 266 and returns the lock. Each lock provides mutual exclusion access at its task 267 priority level. Since there is no preemption or multiprocessor support in EFI, 268 acquiring the lock only consists of raising to the locks TPL. 269 If Lock is NULL, then ASSERT(). 270 If Priority is not a valid TPL value, then ASSERT(). 271 272 @param Lock A pointer to the lock data structure to initialize. 273 @param Priority The EFI TPL associated with the lock. 274 275 @return The lock. 276 277 **/ 278 EFI_LOCK * 279 EFIAPI 280 EfiInitializeLock ( 281 IN OUT EFI_LOCK *Lock, 282 IN EFI_TPL Priority 283 ); 284 285 /** 286 Initializes a basic mutual exclusion lock. 287 288 This macro initializes the contents of a basic mutual exclusion lock to the 289 released state. Each lock provides mutual exclusion access at its task 290 priority level. Since there is no preemption or multiprocessor support in EFI, 291 acquiring the lock only consists of raising to the locks TPL. 292 293 @param Priority The task priority level of the lock. 294 295 @return The lock. 296 297 **/ 298 #define EFI_INITIALIZE_LOCK_VARIABLE(Priority) \ 299 {Priority, TPL_APPLICATION, EfiLockReleased } 300 301 302 /** 303 Macro that calls DebugAssert() if an EFI_LOCK structure is not in the locked state. 304 305 If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED 306 bit of PcdDebugProperyMask is set, then this macro evaluates the EFI_LOCK 307 structure specified by Lock. If Lock is not in the locked state, then 308 DebugAssert() is called passing in the source filename, source line number, 309 and Lock. 310 311 If Lock is NULL, then ASSERT(). 312 313 @param LockParameter A pointer to the lock to acquire. 314 315 **/ 316 #if !defined(MDEPKG_NDEBUG) 317 #define ASSERT_LOCKED(LockParameter) \ 318 do { \ 319 if (DebugAssertEnabled ()) { \ 320 ASSERT (LockParameter != NULL); \ 321 if ((LockParameter)->Lock != EfiLockAcquired) { \ 322 _ASSERT (LockParameter not locked); \ 323 } \ 324 } \ 325 } while (FALSE) 326 #else 327 #define ASSERT_LOCKED(LockParameter) 328 #endif 329 330 331 /** 332 Acquires ownership of a lock. 333 334 This function raises the system's current task priority level to the task 335 priority level of the mutual exclusion lock. Then, it places the lock in the 336 acquired state. 337 If Lock is NULL, then ASSERT(). 338 If Lock is not initialized, then ASSERT(). 339 If Lock is already in the acquired state, then ASSERT(). 340 341 @param Lock A pointer to the lock to acquire. 342 343 **/ 344 VOID 345 EFIAPI 346 EfiAcquireLock ( 347 IN EFI_LOCK *Lock 348 ); 349 350 /** 351 Acquires ownership of a lock. 352 353 This function raises the system's current task priority level to the task priority 354 level of the mutual exclusion lock. Then, it attempts to place the lock in the acquired state. 355 If the lock is already in the acquired state, then EFI_ACCESS_DENIED is returned. 356 Otherwise, EFI_SUCCESS is returned. 357 If Lock is NULL, then ASSERT(). 358 If Lock is not initialized, then ASSERT(). 359 360 @param Lock A pointer to the lock to acquire. 361 362 @retval EFI_SUCCESS The lock was acquired. 363 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned. 364 365 **/ 366 EFI_STATUS 367 EFIAPI 368 EfiAcquireLockOrFail ( 369 IN EFI_LOCK *Lock 370 ); 371 372 /** 373 Releases ownership of a lock. 374 375 This function transitions a mutual exclusion lock from the acquired state to 376 the released state, and restores the system's task priority level to its 377 previous level. 378 If Lock is NULL, then ASSERT(). 379 If Lock is not initialized, then ASSERT(). 380 If Lock is already in the released state, then ASSERT(). 381 382 @param Lock A pointer to the lock to release. 383 384 **/ 385 VOID 386 EFIAPI 387 EfiReleaseLock ( 388 IN EFI_LOCK *Lock 389 ); 390 391 /** 392 Tests whether a controller handle is being managed by a specific driver. 393 394 This function tests whether the driver specified by DriverBindingHandle is 395 currently managing the controller specified by ControllerHandle. This test 396 is performed by evaluating if the the protocol specified by ProtocolGuid is 397 present on ControllerHandle and is was opened by DriverBindingHandle with an 398 attribute of EFI_OPEN_PROTOCOL_BY_DRIVER. 399 If ProtocolGuid is NULL, then ASSERT(). 400 401 @param ControllerHandle A handle for a controller to test. 402 @param DriverBindingHandle Specifies the driver binding handle for the 403 driver. 404 @param ProtocolGuid Specifies the protocol that the driver specified 405 by DriverBindingHandle opens in its Start() 406 function. 407 408 @retval EFI_SUCCESS ControllerHandle is managed by the driver 409 specified by DriverBindingHandle. 410 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the driver 411 specified by DriverBindingHandle. 412 413 **/ 414 EFI_STATUS 415 EFIAPI 416 EfiTestManagedDevice ( 417 IN CONST EFI_HANDLE ControllerHandle, 418 IN CONST EFI_HANDLE DriverBindingHandle, 419 IN CONST EFI_GUID *ProtocolGuid 420 ); 421 422 /** 423 Tests whether a child handle is a child device of the controller. 424 425 This function tests whether ChildHandle is one of the children of 426 ControllerHandle. This test is performed by checking to see if the protocol 427 specified by ProtocolGuid is present on ControllerHandle and opened by 428 ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. 429 If ProtocolGuid is NULL, then ASSERT(). 430 431 @param ControllerHandle A handle for a (parent) controller to test. 432 @param ChildHandle A child handle to test. 433 @param ProtocolGuid Supplies the protocol that the child controller 434 opens on its parent controller. 435 436 @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle. 437 @retval EFI_UNSUPPORTED ChildHandle is not a child of the 438 ControllerHandle. 439 440 **/ 441 EFI_STATUS 442 EFIAPI 443 EfiTestChildHandle ( 444 IN CONST EFI_HANDLE ControllerHandle, 445 IN CONST EFI_HANDLE ChildHandle, 446 IN CONST EFI_GUID *ProtocolGuid 447 ); 448 449 /** 450 This function looks up a Unicode string in UnicodeStringTable. 451 452 If Language is a member of SupportedLanguages and a Unicode string is found in 453 UnicodeStringTable that matches the language code specified by Language, then it 454 is returned in UnicodeString. 455 456 @param Language A pointer to the ISO 639-2 language code for the 457 Unicode string to look up and return. 458 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes 459 that the Unicode string table supports. Language 460 must be a member of this set. 461 @param UnicodeStringTable A pointer to the table of Unicode strings. 462 @param UnicodeString A pointer to the Unicode string from UnicodeStringTable 463 that matches the language specified by Language. 464 465 @retval EFI_SUCCESS The Unicode string that matches the language 466 specified by Language was found 467 in the table of Unicode strings UnicodeStringTable, 468 and it was returned in UnicodeString. 469 @retval EFI_INVALID_PARAMETER Language is NULL. 470 @retval EFI_INVALID_PARAMETER UnicodeString is NULL. 471 @retval EFI_UNSUPPORTED SupportedLanguages is NULL. 472 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL. 473 @retval EFI_UNSUPPORTED The language specified by Language is not a 474 member of SupportedLanguages. 475 @retval EFI_UNSUPPORTED The language specified by Language is not 476 supported by UnicodeStringTable. 477 478 **/ 479 EFI_STATUS 480 EFIAPI 481 LookupUnicodeString ( 482 IN CONST CHAR8 *Language, 483 IN CONST CHAR8 *SupportedLanguages, 484 IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable, 485 OUT CHAR16 **UnicodeString 486 ); 487 488 /** 489 This function looks up a Unicode string in UnicodeStringTable. 490 491 If Language is a member of SupportedLanguages and a Unicode string is found in 492 UnicodeStringTable that matches the language code specified by Language, then 493 it is returned in UnicodeString. 494 495 @param Language A pointer to an ASCII string containing the ISO 639-2 or the 496 RFC 4646 language code for the Unicode string to look up and 497 return. If Iso639Language is TRUE, then this ASCII string is 498 not assumed to be Null-terminated, and only the first three 499 characters are used. If Iso639Language is FALSE, then this ASCII 500 string must be Null-terminated. 501 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains a 502 set of ISO 639-2 or RFC 4646 language codes that the Unicode 503 string table supports. Language must be a member of this set. 504 If Iso639Language is TRUE, then this string contains one or more 505 ISO 639-2 language codes with no separator characters. If Iso639Language 506 is FALSE, then is string contains one or more RFC 4646 language 507 codes separated by ';'. 508 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE 509 is defined in "Related Definitions". 510 @param UnicodeString A pointer to the Null-terminated Unicode string from UnicodeStringTable 511 that matches the language specified by Language. 512 @param Iso639Language Specifies the supported language code format. If it is TRUE, then 513 Language and SupportedLanguages follow ISO 639-2 language code format. 514 Otherwise, they follow the RFC 4646 language code format. 515 516 517 @retval EFI_SUCCESS The Unicode string that matches the language specified by Language 518 was found in the table of Unicode strings UnicodeStringTable, and 519 it was returned in UnicodeString. 520 @retval EFI_INVALID_PARAMETER Language is NULL. 521 @retval EFI_INVALID_PARAMETER UnicodeString is NULL. 522 @retval EFI_UNSUPPORTED SupportedLanguages is NULL. 523 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL. 524 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages. 525 @retval EFI_UNSUPPORTED The language specified by Language is not supported by UnicodeStringTable. 526 527 **/ 528 EFI_STATUS 529 EFIAPI 530 LookupUnicodeString2 ( 531 IN CONST CHAR8 *Language, 532 IN CONST CHAR8 *SupportedLanguages, 533 IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable, 534 OUT CHAR16 **UnicodeString, 535 IN BOOLEAN Iso639Language 536 ); 537 538 /** 539 This function adds a Unicode string to UnicodeStringTable. 540 541 If Language is a member of SupportedLanguages then UnicodeString is added to 542 UnicodeStringTable. New buffers are allocated for both Language and 543 UnicodeString. The contents of Language and UnicodeString are copied into 544 these new buffers. These buffers are automatically freed when 545 FreeUnicodeStringTable() is called. 546 547 @param Language A pointer to the ISO 639-2 language code for the Unicode 548 string to add. 549 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes 550 that the Unicode string table supports. 551 Language must be a member of this set. 552 @param UnicodeStringTable A pointer to the table of Unicode strings. 553 @param UnicodeString A pointer to the Unicode string to add. 554 555 @retval EFI_SUCCESS The Unicode string that matches the language 556 specified by Language was found in the table of 557 Unicode strings UnicodeStringTable, and it was 558 returned in UnicodeString. 559 @retval EFI_INVALID_PARAMETER Language is NULL. 560 @retval EFI_INVALID_PARAMETER UnicodeString is NULL. 561 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string. 562 @retval EFI_UNSUPPORTED SupportedLanguages is NULL. 563 @retval EFI_ALREADY_STARTED A Unicode string with language Language is 564 already present in UnicodeStringTable. 565 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another 566 Unicode string to UnicodeStringTable. 567 @retval EFI_UNSUPPORTED The language specified by Language is not a 568 member of SupportedLanguages. 569 570 **/ 571 EFI_STATUS 572 EFIAPI 573 AddUnicodeString ( 574 IN CONST CHAR8 *Language, 575 IN CONST CHAR8 *SupportedLanguages, 576 IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable, 577 IN CONST CHAR16 *UnicodeString 578 ); 579 580 /** 581 This function adds the Null-terminated Unicode string specified by UnicodeString 582 to UnicodeStringTable. 583 584 If Language is a member of SupportedLanguages then UnicodeString is added to 585 UnicodeStringTable. New buffers are allocated for both Language and UnicodeString. 586 The contents of Language and UnicodeString are copied into these new buffers. 587 These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called. 588 589 @param Language A pointer to an ASCII string containing the ISO 639-2 or 590 the RFC 4646 language code for the Unicode string to add. 591 If Iso639Language is TRUE, then this ASCII string is not 592 assumed to be Null-terminated, and only the first three 593 chacters are used. If Iso639Language is FALSE, then this 594 ASCII string must be Null-terminated. 595 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains 596 a set of ISO 639-2 or RFC 4646 language codes that the Unicode 597 string table supports. Language must be a member of this set. 598 If Iso639Language is TRUE, then this string contains one or more 599 ISO 639-2 language codes with no separator characters. 600 If Iso639Language is FALSE, then is string contains one or more 601 RFC 4646 language codes separated by ';'. 602 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE 603 is defined in "Related Definitions". 604 @param UnicodeString A pointer to the Unicode string to add. 605 @param Iso639Language Specifies the supported language code format. If it is TRUE, 606 then Language and SupportedLanguages follow ISO 639-2 language code format. 607 Otherwise, they follow RFC 4646 language code format. 608 609 @retval EFI_SUCCESS The Unicode string that matches the language specified by 610 Language was found in the table of Unicode strings UnicodeStringTable, 611 and it was returned in UnicodeString. 612 @retval EFI_INVALID_PARAMETER Language is NULL. 613 @retval EFI_INVALID_PARAMETER UnicodeString is NULL. 614 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string. 615 @retval EFI_UNSUPPORTED SupportedLanguages is NULL. 616 @retval EFI_ALREADY_STARTED A Unicode string with language Language is already present in 617 UnicodeStringTable. 618 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another Unicode string UnicodeStringTable. 619 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages. 620 621 **/ 622 EFI_STATUS 623 EFIAPI 624 AddUnicodeString2 ( 625 IN CONST CHAR8 *Language, 626 IN CONST CHAR8 *SupportedLanguages, 627 IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable, 628 IN CONST CHAR16 *UnicodeString, 629 IN BOOLEAN Iso639Language 630 ); 631 632 /** 633 This function frees the table of Unicode strings in UnicodeStringTable. 634 635 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned. 636 Otherwise, each language code, and each Unicode string in the Unicode string 637 table are freed, and EFI_SUCCESS is returned. 638 639 @param UnicodeStringTable A pointer to the table of Unicode strings. 640 641 @retval EFI_SUCCESS The Unicode string table was freed. 642 643 **/ 644 EFI_STATUS 645 EFIAPI 646 FreeUnicodeStringTable ( 647 IN EFI_UNICODE_STRING_TABLE *UnicodeStringTable 648 ); 649 650 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES 651 652 /** 653 [ATTENTION] This function will be deprecated for security reason. 654 655 Returns a pointer to an allocated buffer that contains the contents of a 656 variable retrieved through the UEFI Runtime Service GetVariable(). The 657 returned buffer is allocated using AllocatePool(). The caller is responsible 658 for freeing this buffer with FreePool(). 659 660 If Name is NULL, then ASSERT(). 661 If Guid is NULL, then ASSERT(). 662 663 @param[in] Name The pointer to a Null-terminated Unicode string. 664 @param[in] Guid The pointer to an EFI_GUID structure. 665 666 @retval NULL The variable could not be retrieved. 667 @retval NULL There are not enough resources available for the variable contents. 668 @retval Other A pointer to allocated buffer containing the variable contents. 669 670 **/ 671 VOID * 672 EFIAPI 673 GetVariable ( 674 IN CONST CHAR16 *Name, 675 IN CONST EFI_GUID *Guid 676 ); 677 678 /** 679 [ATTENTION] This function will be deprecated for security reason. 680 681 Returns a pointer to an allocated buffer that contains the contents of a 682 variable retrieved through the UEFI Runtime Service GetVariable(). This 683 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables. 684 The returned buffer is allocated using AllocatePool(). The caller is 685 responsible for freeing this buffer with FreePool(). 686 687 If Name is NULL, then ASSERT(). 688 689 @param[in] Name The pointer to a Null-terminated Unicode string. 690 691 @retval NULL The variable could not be retrieved. 692 @retval NULL There are not enough resources available for the variable contents. 693 @retval Other A pointer to allocated buffer containing the variable contents. 694 695 **/ 696 VOID * 697 EFIAPI 698 GetEfiGlobalVariable ( 699 IN CONST CHAR16 *Name 700 ); 701 #endif 702 703 704 /** 705 Returns the status whether get the variable success. The function retrieves 706 variable through the UEFI Runtime Service GetVariable(). The 707 returned buffer is allocated using AllocatePool(). The caller is responsible 708 for freeing this buffer with FreePool(). 709 710 If Name is NULL, then ASSERT(). 711 If Guid is NULL, then ASSERT(). 712 If Value is NULL, then ASSERT(). 713 714 @param[in] Name The pointer to a Null-terminated Unicode string. 715 @param[in] Guid The pointer to an EFI_GUID structure 716 @param[out] Value The buffer point saved the variable info. 717 @param[out] Size The buffer size of the variable. 718 719 @return EFI_OUT_OF_RESOURCES Allocate buffer failed. 720 @return EFI_SUCCESS Find the specified variable. 721 @return Others Errors Return errors from call to gRT->GetVariable. 722 723 **/ 724 EFI_STATUS 725 EFIAPI 726 GetVariable2 ( 727 IN CONST CHAR16 *Name, 728 IN CONST EFI_GUID *Guid, 729 OUT VOID **Value, 730 OUT UINTN *Size OPTIONAL 731 ); 732 733 /** 734 Returns a pointer to an allocated buffer that contains the contents of a 735 variable retrieved through the UEFI Runtime Service GetVariable(). This 736 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables. 737 The returned buffer is allocated using AllocatePool(). The caller is 738 responsible for freeing this buffer with FreePool(). 739 740 If Name is NULL, then ASSERT(). 741 If Value is NULL, then ASSERT(). 742 743 @param[in] Name The pointer to a Null-terminated Unicode string. 744 @param[out] Value The buffer point saved the variable info. 745 @param[out] Size The buffer size of the variable. 746 747 @return EFI_OUT_OF_RESOURCES Allocate buffer failed. 748 @return EFI_SUCCESS Find the specified variable. 749 @return Others Errors Return errors from call to gRT->GetVariable. 750 751 **/ 752 EFI_STATUS 753 EFIAPI 754 GetEfiGlobalVariable2 ( 755 IN CONST CHAR16 *Name, 756 OUT VOID **Value, 757 OUT UINTN *Size OPTIONAL 758 ); 759 760 /** 761 Returns a pointer to an allocated buffer that contains the best matching language 762 from a set of supported languages. 763 764 This function supports both ISO 639-2 and RFC 4646 language codes, but language 765 code types may not be mixed in a single call to this function. The language 766 code returned is allocated using AllocatePool(). The caller is responsible for 767 freeing the allocated buffer using FreePool(). This function supports a variable 768 argument list that allows the caller to pass in a prioritized list of language 769 codes to test against all the language codes in SupportedLanguages. 770 771 If SupportedLanguages is NULL, then ASSERT(). 772 773 @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string that 774 contains a set of language codes in the format 775 specified by Iso639Language. 776 @param[in] Iso639Language If TRUE, then all language codes are assumed to be 777 in ISO 639-2 format. If FALSE, then all language 778 codes are assumed to be in RFC 4646 language format 779 @param[in] ... A variable argument list that contains pointers to 780 Null-terminated ASCII strings that contain one or more 781 language codes in the format specified by Iso639Language. 782 The first language code from each of these language 783 code lists is used to determine if it is an exact or 784 close match to any of the language codes in 785 SupportedLanguages. Close matches only apply to RFC 4646 786 language codes, and the matching algorithm from RFC 4647 787 is used to determine if a close match is present. If 788 an exact or close match is found, then the matching 789 language code from SupportedLanguages is returned. If 790 no matches are found, then the next variable argument 791 parameter is evaluated. The variable argument list 792 is terminated by a NULL. 793 794 @retval NULL The best matching language could not be found in SupportedLanguages. 795 @retval NULL There are not enough resources available to return the best matching 796 language. 797 @retval Other A pointer to a Null-terminated ASCII string that is the best matching 798 language in SupportedLanguages. 799 800 **/ 801 CHAR8 * 802 EFIAPI 803 GetBestLanguage ( 804 IN CONST CHAR8 *SupportedLanguages, 805 IN BOOLEAN Iso639Language, 806 ... 807 ); 808 809 /** 810 Draws a dialog box to the console output device specified by 811 ConOut defined in the EFI_SYSTEM_TABLE and waits for a keystroke 812 from the console input device specified by ConIn defined in the 813 EFI_SYSTEM_TABLE. 814 815 If there are no strings in the variable argument list, then ASSERT(). 816 If all the strings in the variable argument list are empty, then ASSERT(). 817 818 @param[in] Attribute Specifies the foreground and background color of the popup. 819 @param[out] Key A pointer to the EFI_KEY value of the key that was 820 pressed. This is an optional parameter that may be NULL. 821 If it is NULL then no wait for a keypress will be performed. 822 @param[in] ... The variable argument list that contains pointers to Null- 823 terminated Unicode strings to display in the dialog box. 824 The variable argument list is terminated by a NULL. 825 826 **/ 827 VOID 828 EFIAPI 829 CreatePopUp ( 830 IN UINTN Attribute, 831 OUT EFI_INPUT_KEY *Key, OPTIONAL 832 ... 833 ); 834 835 /** 836 Retrieves the width of a Unicode character. 837 838 This function computes and returns the width of the Unicode character specified 839 by UnicodeChar. 840 841 @param UnicodeChar A Unicode character. 842 843 @retval 0 The width if UnicodeChar could not be determined. 844 @retval 1 UnicodeChar is a narrow glyph. 845 @retval 2 UnicodeChar is a wide glyph. 846 847 **/ 848 UINTN 849 EFIAPI 850 GetGlyphWidth ( 851 IN CHAR16 UnicodeChar 852 ); 853 854 /** 855 Computes the display length of a Null-terminated Unicode String. 856 857 This function computes and returns the display length of the Null-terminated Unicode 858 string specified by String. If String is NULL then 0 is returned. If any of the widths 859 of the Unicode characters in String can not be determined, then 0 is returned. The display 860 width of String can be computed by summing the display widths of each Unicode character 861 in String. Unicode characters that are narrow glyphs have a width of 1, and Unicode 862 characters that are width glyphs have a width of 2. 863 If String is not aligned on a 16-bit boundary, then ASSERT(). 864 865 @param String A pointer to a Null-terminated Unicode string. 866 867 @return The display length of the Null-terminated Unicode string specified by String. 868 869 **/ 870 UINTN 871 EFIAPI 872 UnicodeStringDisplayLength ( 873 IN CONST CHAR16 *String 874 ); 875 876 // 877 // Functions that abstract early Framework contamination of UEFI. 878 // 879 /** 880 Create, Signal, and Close the Ready to Boot event using EfiSignalEventReadyToBoot(). 881 882 This function abstracts the signaling of the Ready to Boot Event. The Framework moved 883 from a proprietary to UEFI 2.0 based mechanism. This library abstracts the caller 884 from how this event is created to prevent to code form having to change with the 885 version of the specification supported. 886 887 **/ 888 VOID 889 EFIAPI 890 EfiSignalEventReadyToBoot ( 891 VOID 892 ); 893 894 /** 895 Create, Signal, and Close the Ready to Boot event using EfiSignalEventLegacyBoot(). 896 897 This function abstracts the signaling of the Legacy Boot Event. The Framework moved from 898 a proprietary to UEFI 2.0 based mechanism. This library abstracts the caller from how 899 this event is created to prevent to code form having to change with the version of the 900 specification supported. 901 902 **/ 903 VOID 904 EFIAPI 905 EfiSignalEventLegacyBoot ( 906 VOID 907 ); 908 909 /** 910 Creates an EFI event in the Legacy Boot Event Group. 911 912 Prior to UEFI 2.0 this was done via a non blessed UEFI extensions and this library 913 abstracts the implementation mechanism of this event from the caller. This function 914 abstracts the creation of the Legacy Boot Event. The Framework moved from a proprietary 915 to UEFI 2.0 based mechanism. This library abstracts the caller from how this event 916 is created to prevent to code form having to change with the version of the 917 specification supported. 918 If LegacyBootEvent is NULL, then ASSERT(). 919 920 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex). 921 922 @retval EFI_SUCCESS The event was created. 923 @retval Other The event was not created. 924 925 **/ 926 EFI_STATUS 927 EFIAPI 928 EfiCreateEventLegacyBoot ( 929 OUT EFI_EVENT *LegacyBootEvent 930 ); 931 932 /** 933 Create an EFI event in the Legacy Boot Event Group and allows 934 the caller to specify a notification function. 935 936 This function abstracts the creation of the Legacy Boot Event. 937 The Framework moved from a proprietary to UEFI 2.0 based mechanism. 938 This library abstracts the caller from how this event is created to prevent 939 to code form having to change with the version of the specification supported. 940 If LegacyBootEvent is NULL, then ASSERT(). 941 942 @param NotifyTpl The task priority level of the event. 943 @param NotifyFunction The notification function to call when the event is signaled. 944 @param NotifyContext The content to pass to NotifyFunction when the event is signaled. 945 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex). 946 947 @retval EFI_SUCCESS The event was created. 948 @retval Other The event was not created. 949 950 **/ 951 EFI_STATUS 952 EFIAPI 953 EfiCreateEventLegacyBootEx ( 954 IN EFI_TPL NotifyTpl, 955 IN EFI_EVENT_NOTIFY NotifyFunction, OPTIONAL 956 IN VOID *NotifyContext, OPTIONAL 957 OUT EFI_EVENT *LegacyBootEvent 958 ); 959 960 /** 961 Create an EFI event in the Ready To Boot Event Group. 962 963 Prior to UEFI 2.0 this was done via a non-standard UEFI extension, and this library 964 abstracts the implementation mechanism of this event from the caller. 965 This function abstracts the creation of the Ready to Boot Event. The Framework 966 moved from a proprietary to UEFI 2.0-based mechanism. This library abstracts 967 the caller from how this event is created to prevent the code form having to 968 change with the version of the specification supported. 969 If ReadyToBootEvent is NULL, then ASSERT(). 970 971 @param ReadyToBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex). 972 973 @retval EFI_SUCCESS The event was created. 974 @retval Other The event was not created. 975 976 **/ 977 EFI_STATUS 978 EFIAPI 979 EfiCreateEventReadyToBoot ( 980 OUT EFI_EVENT *ReadyToBootEvent 981 ); 982 983 /** 984 Create an EFI event in the Ready To Boot Event Group and allows 985 the caller to specify a notification function. 986 987 This function abstracts the creation of the Ready to Boot Event. 988 The Framework moved from a proprietary to UEFI 2.0 based mechanism. 989 This library abstracts the caller from how this event is created to prevent 990 to code form having to change with the version of the specification supported. 991 If ReadyToBootEvent is NULL, then ASSERT(). 992 993 @param NotifyTpl The task priority level of the event. 994 @param NotifyFunction The notification function to call when the event is signaled. 995 @param NotifyContext The content to pass to NotifyFunction when the event is signaled. 996 @param ReadyToBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex). 997 998 @retval EFI_SUCCESS The event was created. 999 @retval Other The event was not created. 1000 1001 **/ 1002 EFI_STATUS 1003 EFIAPI 1004 EfiCreateEventReadyToBootEx ( 1005 IN EFI_TPL NotifyTpl, 1006 IN EFI_EVENT_NOTIFY NotifyFunction, OPTIONAL 1007 IN VOID *NotifyContext, OPTIONAL 1008 OUT EFI_EVENT *ReadyToBootEvent 1009 ); 1010 1011 /** 1012 Initialize a Firmware Volume (FV) Media Device Path node. 1013 1014 The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification. 1015 This library function abstracts initializing a device path node. 1016 Initialize the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure. This device 1017 path changed in the DXE CIS version 0.92 in a non back ward compatible way to 1018 not conflict with the UEFI 2.0 specification. This function abstracts the 1019 differences from the caller. 1020 If FvDevicePathNode is NULL, then ASSERT(). 1021 If NameGuid is NULL, then ASSERT(). 1022 1023 @param FvDevicePathNode The pointer to a FV device path node to initialize 1024 @param NameGuid FV file name to use in FvDevicePathNode 1025 1026 **/ 1027 VOID 1028 EFIAPI 1029 EfiInitializeFwVolDevicepathNode ( 1030 IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode, 1031 IN CONST EFI_GUID *NameGuid 1032 ); 1033 1034 /** 1035 Check to see if the Firmware Volume (FV) Media Device Path is valid 1036 1037 The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification. 1038 This library function abstracts validating a device path node. 1039 Check the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure to see if it's valid. 1040 If it is valid, then return the GUID file name from the device path node. Otherwise, 1041 return NULL. This device path changed in the DXE CIS version 0.92 in a non backward 1042 compatible way to not conflict with the UEFI 2.0 specification. This function abstracts 1043 the differences from the caller. 1044 If FvDevicePathNode is NULL, then ASSERT(). 1045 1046 @param FvDevicePathNode The pointer to FV device path to check. 1047 1048 @retval NULL FvDevicePathNode is not valid. 1049 @retval Other FvDevicePathNode is valid and pointer to NameGuid was returned. 1050 1051 **/ 1052 EFI_GUID * 1053 EFIAPI 1054 EfiGetNameGuidFromFwVolDevicePathNode ( 1055 IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode 1056 ); 1057 1058 /** 1059 Prints a formatted Unicode string to the console output device specified by 1060 ConOut defined in the EFI_SYSTEM_TABLE. 1061 1062 This function prints a formatted Unicode string to the console output device 1063 specified by ConOut in EFI_SYSTEM_TABLE and returns the number of Unicode 1064 characters that printed to ConOut. If the length of the formatted Unicode 1065 string is greater than PcdUefiLibMaxPrintBufferSize, then only the first 1066 PcdUefiLibMaxPrintBufferSize characters are sent to ConOut. 1067 If Format is NULL, then ASSERT(). 1068 If Format is not aligned on a 16-bit boundary, then ASSERT(). 1069 If gST->ConOut is NULL, then ASSERT(). 1070 1071 @param Format A null-terminated Unicode format string. 1072 @param ... The variable argument list whose contents are accessed based 1073 on the format string specified by Format. 1074 1075 @return Number of Unicode characters printed to ConOut. 1076 1077 **/ 1078 UINTN 1079 EFIAPI 1080 Print ( 1081 IN CONST CHAR16 *Format, 1082 ... 1083 ); 1084 1085 /** 1086 Prints a formatted Unicode string to the console output device specified by 1087 StdErr defined in the EFI_SYSTEM_TABLE. 1088 1089 This function prints a formatted Unicode string to the console output device 1090 specified by StdErr in EFI_SYSTEM_TABLE and returns the number of Unicode 1091 characters that printed to StdErr. If the length of the formatted Unicode 1092 string is greater than PcdUefiLibMaxPrintBufferSize, then only the first 1093 PcdUefiLibMaxPrintBufferSize characters are sent to StdErr. 1094 If Format is NULL, then ASSERT(). 1095 If Format is not aligned on a 16-bit boundary, then ASSERT(). 1096 If gST->StdErr is NULL, then ASSERT(). 1097 1098 @param Format A null-terminated Unicode format string. 1099 @param ... The variable argument list whose contents are accessed based 1100 on the format string specified by Format. 1101 1102 @return Number of Unicode characters printed to StdErr. 1103 1104 **/ 1105 UINTN 1106 EFIAPI 1107 ErrorPrint ( 1108 IN CONST CHAR16 *Format, 1109 ... 1110 ); 1111 1112 /** 1113 Prints a formatted ASCII string to the console output device specified by 1114 ConOut defined in the EFI_SYSTEM_TABLE. 1115 1116 This function prints a formatted ASCII string to the console output device 1117 specified by ConOut in EFI_SYSTEM_TABLE and returns the number of ASCII 1118 characters that printed to ConOut. If the length of the formatted ASCII 1119 string is greater than PcdUefiLibMaxPrintBufferSize, then only the first 1120 PcdUefiLibMaxPrintBufferSize characters are sent to ConOut. 1121 If Format is NULL, then ASSERT(). 1122 If gST->ConOut is NULL, then ASSERT(). 1123 1124 @param Format A null-terminated ASCII format string. 1125 @param ... The variable argument list whose contents are accessed based 1126 on the format string specified by Format. 1127 1128 @return Number of ASCII characters printed to ConOut. 1129 1130 **/ 1131 UINTN 1132 EFIAPI 1133 AsciiPrint ( 1134 IN CONST CHAR8 *Format, 1135 ... 1136 ); 1137 1138 /** 1139 Prints a formatted ASCII string to the console output device specified by 1140 StdErr defined in the EFI_SYSTEM_TABLE. 1141 1142 This function prints a formatted ASCII string to the console output device 1143 specified by StdErr in EFI_SYSTEM_TABLE and returns the number of ASCII 1144 characters that printed to StdErr. If the length of the formatted ASCII 1145 string is greater than PcdUefiLibMaxPrintBufferSize, then only the first 1146 PcdUefiLibMaxPrintBufferSize characters are sent to StdErr. 1147 If Format is NULL, then ASSERT(). 1148 If gST->StdErr is NULL, then ASSERT(). 1149 1150 @param Format A null-terminated ASCII format string. 1151 @param ... The variable argument list whose contents are accessed based 1152 on the format string specified by Format. 1153 1154 @return Number of ASCII characters printed to ConErr. 1155 1156 **/ 1157 UINTN 1158 EFIAPI 1159 AsciiErrorPrint ( 1160 IN CONST CHAR8 *Format, 1161 ... 1162 ); 1163 1164 1165 /** 1166 Prints a formatted Unicode string to a graphics console device specified by 1167 ConsoleOutputHandle defined in the EFI_SYSTEM_TABLE at the given (X,Y) coordinates. 1168 1169 This function prints a formatted Unicode string to the graphics console device 1170 specified by ConsoleOutputHandle in EFI_SYSTEM_TABLE and returns the number of 1171 Unicode characters displayed, not including partial characters that may be clipped 1172 by the right edge of the display. If the length of the formatted Unicode string is 1173 greater than PcdUefiLibMaxPrintBufferSize, then at most the first 1174 PcdUefiLibMaxPrintBufferSize characters are printed. The EFI_HII_FONT_PROTOCOL 1175 is used to convert the string to a bitmap using the glyphs registered with the 1176 HII database. No wrapping is performed, so any portions of the string the fall 1177 outside the active display region will not be displayed. 1178 1179 If a graphics console device is not associated with the ConsoleOutputHandle 1180 defined in the EFI_SYSTEM_TABLE then no string is printed, and 0 is returned. 1181 If the EFI_HII_FONT_PROTOCOL is not present in the handle database, then no 1182 string is printed, and 0 is returned. 1183 If Format is NULL, then ASSERT(). 1184 If Format is not aligned on a 16-bit boundary, then ASSERT(). 1185 If gST->ConsoleOutputHandle is NULL, then ASSERT(). 1186 1187 @param PointX X coordinate to print the string. 1188 @param PointY Y coordinate to print the string. 1189 @param ForeGround The foreground color of the string being printed. This is 1190 an optional parameter that may be NULL. If it is NULL, 1191 then the foreground color of the current ConOut device 1192 in the EFI_SYSTEM_TABLE is used. 1193 @param BackGround The background color of the string being printed. This is 1194 an optional parameter that may be NULL. If it is NULL, 1195 then the background color of the current ConOut device 1196 in the EFI_SYSTEM_TABLE is used. 1197 @param Format A null-terminated Unicode format string. See Print Library 1198 for the supported format string syntax. 1199 @param ... Variable argument list whose contents are accessed based on 1200 the format string specified by Format. 1201 1202 @return The number of Unicode characters printed. 1203 1204 **/ 1205 UINTN 1206 EFIAPI 1207 PrintXY ( 1208 IN UINTN PointX, 1209 IN UINTN PointY, 1210 IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL *ForeGround, OPTIONAL 1211 IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL *BackGround, OPTIONAL 1212 IN CONST CHAR16 *Format, 1213 ... 1214 ); 1215 1216 /** 1217 Prints a formatted ASCII string to a graphics console device specified by 1218 ConsoleOutputHandle defined in the EFI_SYSTEM_TABLE at the given (X,Y) coordinates. 1219 1220 This function prints a formatted ASCII string to the graphics console device 1221 specified by ConsoleOutputHandle in EFI_SYSTEM_TABLE and returns the number of 1222 ASCII characters displayed, not including partial characters that may be clipped 1223 by the right edge of the display. If the length of the formatted ASCII string is 1224 greater than PcdUefiLibMaxPrintBufferSize, then at most the first 1225 PcdUefiLibMaxPrintBufferSize characters are printed. The EFI_HII_FONT_PROTOCOL 1226 is used to convert the string to a bitmap using the glyphs registered with the 1227 HII database. No wrapping is performed, so any portions of the string the fall 1228 outside the active display region will not be displayed. 1229 1230 If a graphics console device is not associated with the ConsoleOutputHandle 1231 defined in the EFI_SYSTEM_TABLE then no string is printed, and 0 is returned. 1232 If the EFI_HII_FONT_PROTOCOL is not present in the handle database, then no 1233 string is printed, and 0 is returned. 1234 If Format is NULL, then ASSERT(). 1235 If gST->ConsoleOutputHandle is NULL, then ASSERT(). 1236 1237 @param PointX X coordinate to print the string. 1238 @param PointY Y coordinate to print the string. 1239 @param ForeGround The foreground color of the string being printed. This is 1240 an optional parameter that may be NULL. If it is NULL, 1241 then the foreground color of the current ConOut device 1242 in the EFI_SYSTEM_TABLE is used. 1243 @param BackGround The background color of the string being printed. This is 1244 an optional parameter that may be NULL. If it is NULL, 1245 then the background color of the current ConOut device 1246 in the EFI_SYSTEM_TABLE is used. 1247 @param Format A null-terminated ASCII format string. See Print Library 1248 for the supported format string syntax. 1249 @param ... The variable argument list whose contents are accessed based on 1250 the format string specified by Format. 1251 1252 @return The number of ASCII characters printed. 1253 1254 **/ 1255 UINTN 1256 EFIAPI 1257 AsciiPrintXY ( 1258 IN UINTN PointX, 1259 IN UINTN PointY, 1260 IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL *ForeGround, OPTIONAL 1261 IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL *BackGround, OPTIONAL 1262 IN CONST CHAR8 *Format, 1263 ... 1264 ); 1265 1266 /** 1267 Installs and completes the initialization of a Driver Binding Protocol instance. 1268 1269 Installs the Driver Binding Protocol specified by DriverBinding onto the handle 1270 specified by DriverBindingHandle. If DriverBindingHandle is NULL, then DriverBinding 1271 is installed onto a newly created handle. DriverBindingHandle is typically the same 1272 as the driver's ImageHandle, but it can be different if the driver produces multiple 1273 Driver Binding Protocols. 1274 If DriverBinding is NULL, then ASSERT(). 1275 If DriverBinding can not be installed onto a handle, then ASSERT(). 1276 1277 @param ImageHandle The image handle of the driver. 1278 @param SystemTable The EFI System Table that was passed to the driver's entry point. 1279 @param DriverBinding A Driver Binding Protocol instance that this driver is producing. 1280 @param DriverBindingHandle The handle that DriverBinding is to be installed onto. If this 1281 parameter is NULL, then a new handle is created. 1282 1283 @retval EFI_SUCCESS The protocol installation completed successfully. 1284 @retval EFI_OUT_OF_RESOURCES There was not enough system resources to install the protocol. 1285 @retval Others Status from gBS->InstallMultipleProtocolInterfaces(). 1286 1287 **/ 1288 EFI_STATUS 1289 EFIAPI 1290 EfiLibInstallDriverBinding ( 1291 IN CONST EFI_HANDLE ImageHandle, 1292 IN CONST EFI_SYSTEM_TABLE *SystemTable, 1293 IN EFI_DRIVER_BINDING_PROTOCOL *DriverBinding, 1294 IN EFI_HANDLE DriverBindingHandle 1295 ); 1296 1297 1298 /** 1299 Installs and completes the initialization of a Driver Binding Protocol instance and 1300 optionally installs the Component Name, Driver Configuration and Driver Diagnostics Protocols. 1301 1302 Initializes a driver by installing the Driver Binding Protocol together with the 1303 optional Component Name, optional Driver Configure and optional Driver Diagnostic 1304 Protocols onto the driver's DriverBindingHandle. If DriverBindingHandle is NULL, 1305 then the protocols are installed onto a newly created handle. DriverBindingHandle 1306 is typically the same as the driver's ImageHandle, but it can be different if the 1307 driver produces multiple Driver Binding Protocols. 1308 If DriverBinding is NULL, then ASSERT(). 1309 If the installation fails, then ASSERT(). 1310 1311 @param ImageHandle The image handle of the driver. 1312 @param SystemTable The EFI System Table that was passed to the driver's entry point. 1313 @param DriverBinding A Driver Binding Protocol instance that this driver is producing. 1314 @param DriverBindingHandle The handle that DriverBinding is to be installed onto. If this 1315 parameter is NULL, then a new handle is created. 1316 @param ComponentName A Component Name Protocol instance that this driver is producing. 1317 @param DriverConfiguration A Driver Configuration Protocol instance that this driver is producing. 1318 @param DriverDiagnostics A Driver Diagnostics Protocol instance that this driver is producing. 1319 1320 @retval EFI_SUCCESS The protocol installation completed successfully. 1321 @retval EFI_OUT_OF_RESOURCES There was not enough memory in the pool to install all the protocols. 1322 1323 **/ 1324 EFI_STATUS 1325 EFIAPI 1326 EfiLibInstallAllDriverProtocols ( 1327 IN CONST EFI_HANDLE ImageHandle, 1328 IN CONST EFI_SYSTEM_TABLE *SystemTable, 1329 IN EFI_DRIVER_BINDING_PROTOCOL *DriverBinding, 1330 IN EFI_HANDLE DriverBindingHandle, 1331 IN CONST EFI_COMPONENT_NAME_PROTOCOL *ComponentName, OPTIONAL 1332 IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL *DriverConfiguration, OPTIONAL 1333 IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL *DriverDiagnostics OPTIONAL 1334 ); 1335 1336 1337 1338 /** 1339 Installs Driver Binding Protocol with optional Component Name and Component Name 2 Protocols. 1340 1341 Initializes a driver by installing the Driver Binding Protocol together with the 1342 optional Component Name and optional Component Name 2 protocols onto the driver's 1343 DriverBindingHandle. If DriverBindingHandle is NULL, then the protocols are installed 1344 onto a newly created handle. DriverBindingHandle is typically the same as the driver's 1345 ImageHandle, but it can be different if the driver produces multiple Driver Binding Protocols. 1346 If DriverBinding is NULL, then ASSERT(). 1347 If the installation fails, then ASSERT(). 1348 1349 @param ImageHandle The image handle of the driver. 1350 @param SystemTable The EFI System Table that was passed to the driver's entry point. 1351 @param DriverBinding A Driver Binding Protocol instance that this driver is producing. 1352 @param DriverBindingHandle The handle that DriverBinding is to be installed onto. If this 1353 parameter is NULL, then a new handle is created. 1354 @param ComponentName A Component Name Protocol instance that this driver is producing. 1355 @param ComponentName2 A Component Name 2 Protocol instance that this driver is producing. 1356 1357 @retval EFI_SUCCESS The protocol installation completed successfully. 1358 @retval EFI_OUT_OF_RESOURCES There was not enough memory in pool to install all the protocols. 1359 1360 **/ 1361 EFI_STATUS 1362 EFIAPI 1363 EfiLibInstallDriverBindingComponentName2 ( 1364 IN CONST EFI_HANDLE ImageHandle, 1365 IN CONST EFI_SYSTEM_TABLE *SystemTable, 1366 IN EFI_DRIVER_BINDING_PROTOCOL *DriverBinding, 1367 IN EFI_HANDLE DriverBindingHandle, 1368 IN CONST EFI_COMPONENT_NAME_PROTOCOL *ComponentName, OPTIONAL 1369 IN CONST EFI_COMPONENT_NAME2_PROTOCOL *ComponentName2 OPTIONAL 1370 ); 1371 1372 1373 /** 1374 Installs Driver Binding Protocol with optional Component Name, Component Name 2, Driver 1375 Configuration, Driver Configuration 2, Driver Diagnostics, and Driver Diagnostics 2 Protocols. 1376 1377 Initializes a driver by installing the Driver Binding Protocol together with the optional 1378 Component Name, optional Component Name 2, optional Driver Configuration, optional Driver Configuration 2, 1379 optional Driver Diagnostic, and optional Driver Diagnostic 2 Protocols onto the driver's DriverBindingHandle. 1380 DriverBindingHandle is typically the same as the driver's ImageHandle, but it can be different if the driver 1381 produces multiple Driver Binding Protocols. 1382 If DriverBinding is NULL, then ASSERT(). 1383 If the installation fails, then ASSERT(). 1384 1385 1386 @param ImageHandle The image handle of the driver. 1387 @param SystemTable The EFI System Table that was passed to the driver's entry point. 1388 @param DriverBinding A Driver Binding Protocol instance that this driver is producing. 1389 @param DriverBindingHandle The handle that DriverBinding is to be installed onto. If this 1390 parameter is NULL, then a new handle is created. 1391 @param ComponentName A Component Name Protocol instance that this driver is producing. 1392 @param ComponentName2 A Component Name 2 Protocol instance that this driver is producing. 1393 @param DriverConfiguration A Driver Configuration Protocol instance that this driver is producing. 1394 @param DriverConfiguration2 A Driver Configuration Protocol 2 instance that this driver is producing. 1395 @param DriverDiagnostics A Driver Diagnostics Protocol instance that this driver is producing. 1396 @param DriverDiagnostics2 A Driver Diagnostics Protocol 2 instance that this driver is producing. 1397 1398 @retval EFI_SUCCESS The protocol installation completed successfully. 1399 @retval EFI_OUT_OF_RESOURCES There was not enough memory in pool to install all the protocols. 1400 1401 **/ 1402 EFI_STATUS 1403 EFIAPI 1404 EfiLibInstallAllDriverProtocols2 ( 1405 IN CONST EFI_HANDLE ImageHandle, 1406 IN CONST EFI_SYSTEM_TABLE *SystemTable, 1407 IN EFI_DRIVER_BINDING_PROTOCOL *DriverBinding, 1408 IN EFI_HANDLE DriverBindingHandle, 1409 IN CONST EFI_COMPONENT_NAME_PROTOCOL *ComponentName, OPTIONAL 1410 IN CONST EFI_COMPONENT_NAME2_PROTOCOL *ComponentName2, OPTIONAL 1411 IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL *DriverConfiguration, OPTIONAL 1412 IN CONST EFI_DRIVER_CONFIGURATION2_PROTOCOL *DriverConfiguration2, OPTIONAL 1413 IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL *DriverDiagnostics, OPTIONAL 1414 IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL *DriverDiagnostics2 OPTIONAL 1415 ); 1416 1417 /** 1418 Appends a formatted Unicode string to a Null-terminated Unicode string 1419 1420 This function appends a formatted Unicode string to the Null-terminated 1421 Unicode string specified by String. String is optional and may be NULL. 1422 Storage for the formatted Unicode string returned is allocated using 1423 AllocatePool(). The pointer to the appended string is returned. The caller 1424 is responsible for freeing the returned string. 1425 1426 If String is not NULL and not aligned on a 16-bit boundary, then ASSERT(). 1427 If FormatString is NULL, then ASSERT(). 1428 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 1429 1430 @param[in] String A Null-terminated Unicode string. 1431 @param[in] FormatString A Null-terminated Unicode format string. 1432 @param[in] Marker VA_LIST marker for the variable argument list. 1433 1434 @retval NULL There was not enough available memory. 1435 @return Null-terminated Unicode string is that is the formatted 1436 string appended to String. 1437 **/ 1438 CHAR16* 1439 EFIAPI 1440 CatVSPrint ( 1441 IN CHAR16 *String, OPTIONAL 1442 IN CONST CHAR16 *FormatString, 1443 IN VA_LIST Marker 1444 ); 1445 1446 /** 1447 Appends a formatted Unicode string to a Null-terminated Unicode string 1448 1449 This function appends a formatted Unicode string to the Null-terminated 1450 Unicode string specified by String. String is optional and may be NULL. 1451 Storage for the formatted Unicode string returned is allocated using 1452 AllocatePool(). The pointer to the appended string is returned. The caller 1453 is responsible for freeing the returned string. 1454 1455 If String is not NULL and not aligned on a 16-bit boundary, then ASSERT(). 1456 If FormatString is NULL, then ASSERT(). 1457 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 1458 1459 @param[in] String A Null-terminated Unicode string. 1460 @param[in] FormatString A Null-terminated Unicode format string. 1461 @param[in] ... The variable argument list whose contents are 1462 accessed based on the format string specified by 1463 FormatString. 1464 1465 @retval NULL There was not enough available memory. 1466 @return Null-terminated Unicode string is that is the formatted 1467 string appended to String. 1468 **/ 1469 CHAR16 * 1470 EFIAPI 1471 CatSPrint ( 1472 IN CHAR16 *String, OPTIONAL 1473 IN CONST CHAR16 *FormatString, 1474 ... 1475 ); 1476 1477 #endif 1478
