IntelFrameworkModulePkg/Include/Library/GenericBdsLib.h

   1 /** @file
   2   Generic BDS library defines general interfaces for BDS driver including:
   3     1) BDS boot policy interface;
   4     2) BDS boot device connect interface;
   5     3) BDS Misc interfaces for mainting boot variable, ouput string.
   6
   7 Copyright (c) 2004 - 2009, Intel Corporation. <BR>
   8 All rights reserved. This program and the accompanying materials
   9 are licensed and made available under the terms and conditions of the BSD License
  10 which accompanies this distribution.  The full text of the license may be found at
  11 http://opensource.org/licenses/bsd-license.php
  12
  13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #ifndef _GENERIC_BDS_LIB_H_
  19 #define _GENERIC_BDS_LIB_H_
  20
  21 extern EFI_HANDLE mBdsImageHandle;
  22
  23 //
  24 // Constants which are variable names used to access variables
  25 //
  26 #define VAR_LEGACY_DEV_ORDER L"LegacyDevOrder"
  27
  28 //
  29 // Data structures and defines
  30 //
  31 #define FRONT_PAGE_QUESTION_ID  0x0000
  32 #define FRONT_PAGE_DATA_WIDTH   0x01
  33
  34 //
  35 // ConnectType
  36 //
  37 #define CONSOLE_OUT 0x00000001
  38 #define STD_ERROR   0x00000002
  39 #define CONSOLE_IN  0x00000004
  40 #define CONSOLE_ALL (CONSOLE_OUT | CONSOLE_IN | STD_ERROR)
  41
  42 //
  43 // Load Option Attributes defined in EFI Specification
  44 //
  45 #define LOAD_OPTION_ACTIVE              0x00000001
  46 #define LOAD_OPTION_FORCE_RECONNECT     0x00000002
  47
  48 #define LOAD_OPTION_HIDDEN              0x00000008
  49 #define LOAD_OPTION_CATEGORY            0x00001F00
  50
  51 #define LOAD_OPTION_CATEGORY_BOOT       0x00000000
  52 #define LOAD_OPTION_CATEGORY_APP        0x00000100
  53
  54 #define EFI_BOOT_OPTION_SUPPORT_KEY     0x00000001
  55 #define EFI_BOOT_OPTION_SUPPORT_APP     0x00000002
  56
  57 #define IS_LOAD_OPTION_TYPE(_c, _Mask)  (BOOLEAN) (((_c) & (_Mask)) != 0)
  58
  59 //
  60 // Define Maxmim characters that will be accepted
  61 //
  62 #define MAX_CHAR            480
  63 #define MAX_CHAR_SIZE       (MAX_CHAR * 2)
  64
  65 #define MIN_ALIGNMENT_SIZE  4
  66 #define ALIGN_SIZE(a)       ((a % MIN_ALIGNMENT_SIZE) ? MIN_ALIGNMENT_SIZE - (a % MIN_ALIGNMENT_SIZE) : 0)
  67
  68 //
  69 // Define maximum characters for boot option variable "BootXXXX"
  70 //
  71 #define BOOT_OPTION_MAX_CHAR 10
  72
  73 //
  74 // This data structure is the part of BDS_CONNECT_ENTRY that we can hard code.
  75 //
  76 #define BDS_LOAD_OPTION_SIGNATURE SIGNATURE_32 ('B', 'd', 'C', 'O')
  77
  78 typedef struct {
  79
  80   UINTN                     Signature;
  81   LIST_ENTRY                Link;
  82
  83   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
  84
  85   CHAR16                    *OptionName;
  86   UINTN                     OptionNumber;
  87   UINT16                    BootCurrent;
  88   UINT32                    Attribute;
  89   CHAR16                    *Description;
  90   VOID                      *LoadOptions;
  91   UINT32                    LoadOptionsSize;
  92   CHAR16                    *StatusString;
  93
  94 } BDS_COMMON_OPTION;
  95
  96 typedef struct {
  97   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
  98   UINTN                     ConnectType;
  99 } BDS_CONSOLE_CONNECT_ENTRY;
 100
 101 //
 102 // Lib Functions
 103 //
 104
 105 //
 106 // Bds boot related lib functions
 107 //
 108 /**
 109   Boot from the UEFI spec defined "BootNext" variable.
 110
 111 **/
 112 VOID
 113 EFIAPI
 114 BdsLibBootNext (
 115   VOID
 116   );
 117
 118 /**
 119   Process the boot option follow the UEFI specification and
 120   special treat the legacy boot option with BBS_DEVICE_PATH.
 121
 122   @param  Option                 The boot option need to be processed
 123   @param  DevicePath             The device path which describe where to load the
 124                                  boot image or the legcy BBS device path to boot
 125                                  the legacy OS
 126   @param  ExitDataSize           The size of exit data.
 127   @param  ExitData               Data returned when Boot image failed.
 128
 129   @retval EFI_SUCCESS            Boot from the input boot option successfully.
 130   @retval EFI_NOT_FOUND          If the Device Path is not found in the system
 131
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 BdsLibBootViaBootOption (
 136   IN  BDS_COMMON_OPTION             * Option,
 137   IN  EFI_DEVICE_PATH_PROTOCOL      * DevicePath,
 138   OUT UINTN                         *ExitDataSize,
 139   OUT CHAR16                        **ExitData OPTIONAL
 140   );
 141
 142
 143 /**
 144   For EFI boot option, BDS separate them as six types:
 145   1. Network - The boot option points to the SimpleNetworkProtocol device.
 146                Bds will try to automatically create this type boot option when enumerate.
 147   2. Shell   - The boot option points to internal flash shell.
 148                Bds will try to automatically create this type boot option when enumerate.
 149   3. Removable BlockIo      - The boot option only points to the removable media
 150                               device, like USB flash disk, DVD, Floppy etc.
 151                               These device should contain a *removable* blockIo
 152                               protocol in their device handle.
 153                               Bds will try to automatically create this type boot option
 154                               when enumerate.
 155   4. Fixed BlockIo          - The boot option only points to a Fixed blockIo device,
 156                               like HardDisk.
 157                               These device should contain a *fixed* blockIo
 158                               protocol in their device handle.
 159                               BDS will skip fixed blockIo devices, and NOT
 160                               automatically create boot option for them. But BDS
 161                               will help to delete those fixed blockIo boot option,
 162                               whose description rule conflict with other auto-created
 163                               boot options.
 164   5. Non-BlockIo Simplefile - The boot option points to a device whose handle
 165                               has SimpleFileSystem Protocol, but has no blockio
 166                               protocol. These devices do not offer blockIo
 167                               protocol, but BDS still can get the
 168                               \EFI\BOOT\boot{machinename}.EFI by SimpleFileSystem
 169                               Protocol.
 170   6. File    - The boot option points to a file. These boot options are usually
 171                created by user manually or OS loader. BDS will not delete or modify
 172                these boot options.
 173
 174   This function will enumerate all possible boot device in the system, and
 175   automatically create boot options for Network, Shell, Removable BlockIo,
 176   and Non-BlockIo Simplefile devices.
 177   It will only excute once of every boot.
 178
 179   @param  BdsBootOptionList      The header of the link list which indexed all
 180                                  current boot options
 181
 182   @retval EFI_SUCCESS            Finished all the boot device enumerate and create
 183                                  the boot option base on that boot device
 184
 185 **/
 186 EFI_STATUS
 187 EFIAPI
 188 BdsLibEnumerateAllBootOption (
 189   IN OUT LIST_ENTRY          *BdsBootOptionList
 190   );
 191
 192 /**
 193   Build the boot option with the handle parsed in
 194
 195   @param  Handle                 The handle which present the device path to create
 196                                  boot option
 197   @param  BdsBootOptionList      The header of the link list which indexed all
 198                                  current boot options
 199   @param  String                 The description of the boot option.
 200
 201 **/
 202 VOID
 203 EFIAPI
 204 BdsLibBuildOptionFromHandle (
 205   IN  EFI_HANDLE                 Handle,
 206   IN  LIST_ENTRY                 *BdsBootOptionList,
 207   IN  CHAR16                     *String
 208   );
 209
 210
 211 /**
 212   Build the on flash shell boot option with the handle parsed in.
 213
 214   @param  Handle                 The handle which present the device path to create
 215                                  on flash shell boot option
 216   @param  BdsBootOptionList      The header of the link list which indexed all
 217                                  current boot options
 218
 219 **/
 220 VOID
 221 EFIAPI
 222 BdsLibBuildOptionFromShell (
 223   IN EFI_HANDLE                  Handle,
 224   IN OUT LIST_ENTRY              *BdsBootOptionList
 225   );
 226
 227 //
 228 // Bds misc lib functions
 229 //
 230 /**
 231   Get boot mode by looking up configuration table and parsing HOB list
 232
 233   @param  BootMode              Boot mode from PEI handoff HOB.
 234
 235   @retval EFI_SUCCESS           Successfully get boot mode
 236
 237 **/
 238 EFI_STATUS
 239 EFIAPI
 240 BdsLibGetBootMode (
 241   OUT EFI_BOOT_MODE       *BootMode
 242   );
 243
 244
 245 /**
 246   The function will go through the driver optoin link list, load and start
 247   every driver the driver optoin device path point to.
 248
 249   @param  BdsDriverLists        The header of the current driver option link list
 250
 251 **/
 252 VOID
 253 EFIAPI
 254 BdsLibLoadDrivers (
 255   IN LIST_ENTRY                   *BdsDriverLists
 256   );
 257
 258
 259 /**
 260   Process BootOrder, or DriverOrder variables, by calling
 261   BdsLibVariableToOption () for each UINT16 in the variables.
 262
 263   @param  BdsCommonOptionList   The header of the option list base on variable
 264                                 VariableName
 265   @param  VariableName          EFI Variable name indicate the BootOrder or
 266                                 DriverOrder
 267
 268   @retval EFI_SUCCESS           Success create the boot option or driver option
 269                                 list
 270   @retval EFI_OUT_OF_RESOURCES  Failed to get the boot option or driver option list
 271
 272 **/
 273 EFI_STATUS
 274 EFIAPI
 275 BdsLibBuildOptionFromVar (
 276   IN  LIST_ENTRY                      *BdsCommonOptionList,
 277   IN  CHAR16                          *VariableName
 278   );
 279
 280 /**
 281   Read the EFI variable (VendorGuid/Name) and return a dynamically allocated
 282   buffer, and the size of the buffer. If failure return NULL.
 283
 284   @param  Name                  String part of EFI variable name
 285   @param  VendorGuid            GUID part of EFI variable name
 286   @param  VariableSize          Returns the size of the EFI variable that was read
 287
 288   @return                       Dynamically allocated memory that contains a copy of the EFI variable
 289                                 Caller is responsible freeing the buffer.
 290   @retval NULL                  Variable was not read
 291
 292 **/
 293 VOID *
 294 EFIAPI
 295 BdsLibGetVariableAndSize (
 296   IN  CHAR16              *Name,
 297   IN  EFI_GUID            *VendorGuid,
 298   OUT UINTN               *VariableSize
 299   );
 300
 301
 302 /**
 303   This function prints a series of strings.
 304
 305   @param  ConOut                Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL
 306   @param  ...                   A variable argument list containing series of
 307                                 strings, the last string must be NULL.
 308
 309   @retval EFI_SUCCESS           Success print out the string using ConOut.
 310   @retval EFI_STATUS            Return the status of the ConOut->OutputString ().
 311
 312 **/
 313 EFI_STATUS
 314 EFIAPI
 315 BdsLibOutputStrings (
 316   IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL   *ConOut,
 317   ...
 318   );
 319
 320 /**
 321   Build the boot#### or driver#### option from the VariableName, the
 322   build boot#### or driver#### will also be linked to BdsCommonOptionList.
 323
 324   @param  BdsCommonOptionList   The header of the boot#### or driver#### option
 325                                 link list
 326   @param  VariableName          EFI Variable name indicate if it is boot#### or
 327                                 driver####
 328
 329   @retval BDS_COMMON_OPTION     Get the option just been created
 330   @retval NULL                  Failed to get the new option
 331
 332 **/
 333 BDS_COMMON_OPTION *
 334 EFIAPI
 335 BdsLibVariableToOption (
 336   IN OUT LIST_ENTRY                   *BdsCommonOptionList,
 337   IN  CHAR16                          *VariableName
 338   );
 339
 340 /**
 341   This function will register the new boot#### or driver#### option base on
 342   the VariableName. The new registered boot#### or driver#### will be linked
 343   to BdsOptionList and also update to the VariableName. After the boot#### or
 344   driver#### updated, the BootOrder or DriverOrder will also be updated.
 345
 346   @param  BdsOptionList         The header of the boot#### or driver#### link list
 347   @param  DevicePath            The device path which the boot#### or driver####
 348                                 option present
 349   @param  String                The description of the boot#### or driver####
 350   @param  VariableName          Indicate if the boot#### or driver#### option
 351
 352   @retval EFI_SUCCESS           The boot#### or driver#### have been success
 353                                 registered
 354   @retval EFI_STATUS            Return the status of gRT->SetVariable ().
 355
 356 **/
 357 EFI_STATUS
 358 EFIAPI
 359 BdsLibRegisterNewOption (
 360   IN  LIST_ENTRY                     *BdsOptionList,
 361   IN  EFI_DEVICE_PATH_PROTOCOL       *DevicePath,
 362   IN  CHAR16                         *String,
 363   IN  CHAR16                         *VariableName
 364   );
 365
 366 //
 367 // Bds connect or disconnect driver lib funcion
 368 //
 369 /**
 370   Connects all drivers to all controllers.
 371   This function make sure all the current system driver will manage
 372   the correspoinding controllers if have. And at the same time, make
 373   sure all the system controllers have driver to manage it if have.
 374
 375 **/
 376 VOID
 377 EFIAPI
 378 BdsLibConnectAllDriversToAllControllers (
 379   VOID
 380   );
 381
 382 /**
 383   This function will connect all the system driver to controller
 384   first, and then special connect the default console, this make
 385   sure all the system controller available and the platform default
 386   console connected.
 387
 388 **/
 389 VOID
 390 EFIAPI
 391 BdsLibConnectAll (
 392   VOID
 393   );
 394
 395 /**
 396   This function will create all handles associate with every device
 397   path node. If the handle associate with one device path node can not
 398   be created success, then still give one chance to do the dispatch,
 399   which load the missing drivers if possible.
 400
 401   @param  DevicePathToConnect   The device path which will be connected, it can be
 402                                 a multi-instance device path
 403
 404   @retval EFI_SUCCESS           All handles associate with every device path  node
 405                                 have been created
 406   @retval EFI_OUT_OF_RESOURCES  There is no resource to create new handles
 407   @retval EFI_NOT_FOUND         Create the handle associate with one device  path
 408                                 node failed
 409
 410 **/
 411 EFI_STATUS
 412 EFIAPI
 413 BdsLibConnectDevicePath (
 414   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePathToConnect
 415   );
 416
 417 /**
 418   This function will connect all current system handles recursively.
 419
 420   gBS->ConnectController() service is invoked for each handle exist in system handler buffer.
 421   If the handle is bus type handler, all childrens also will be connected recursively
 422   by gBS->ConnectController().
 423
 424   @retval EFI_SUCCESS           All handles and it's child handle have been connected
 425   @retval EFI_STATUS            Error status returned by of gBS->LocateHandleBuffer().
 426
 427 **/
 428 EFI_STATUS
 429 EFIAPI
 430 BdsLibConnectAllEfi (
 431   VOID
 432   );
 433
 434 /**
 435   This function will disconnect all current system handles.
 436
 437   gBS->DisconnectController() is invoked for each handle exists in system handle buffer.
 438   If handle is a bus type handle, all childrens also are disconnected recursively by
 439   gBS->DisconnectController().
 440
 441   @retval EFI_SUCCESS           All handles have been disconnected
 442   @retval EFI_STATUS            Error status returned by of gBS->LocateHandleBuffer().
 443
 444 **/
 445 EFI_STATUS
 446 EFIAPI
 447 BdsLibDisconnectAllEfi (
 448   VOID
 449   );
 450
 451 //
 452 // Bds console related lib functions
 453 //
 454 /**
 455   This function will search every simpletxt devive in current system,
 456   and make every simpletxt device as pertantial console device.
 457
 458 **/
 459 VOID
 460 EFIAPI
 461 BdsLibConnectAllConsoles (
 462   VOID
 463   );
 464
 465
 466 /**
 467   This function will connect console device base on the console
 468   device variable ConIn, ConOut and ErrOut.
 469
 470   @retval EFI_SUCCESS              At least one of the ConIn and ConOut device have
 471                                    been connected success.
 472   @retval EFI_STATUS               Return the status of BdsLibConnectConsoleVariable ().
 473
 474 **/
 475 EFI_STATUS
 476 EFIAPI
 477 BdsLibConnectAllDefaultConsoles (
 478   VOID
 479   );
 480
 481 /**
 482   This function update console variable based on ConVarName, it can
 483   add or remove one specific console device path from the variable
 484
 485   @param  ConVarName               Console related variable name, ConIn, ConOut,
 486                                    ErrOut.
 487   @param  CustomizedConDevicePath  The console device path which will be added to
 488                                    the console variable ConVarName, this parameter
 489                                    can not be multi-instance.
 490   @param  ExclusiveDevicePath      The console device path which will be removed
 491                                    from the console variable ConVarName, this
 492                                    parameter can not be multi-instance.
 493
 494   @retval EFI_UNSUPPORTED          The added device path is same to the removed one.
 495   @retval EFI_SUCCESS              Success add or remove the device path from  the
 496                                    console variable.
 497
 498 **/
 499 EFI_STATUS
 500 EFIAPI
 501 BdsLibUpdateConsoleVariable (
 502   IN  CHAR16                    *ConVarName,
 503   IN  EFI_DEVICE_PATH_PROTOCOL  *CustomizedConDevicePath,
 504   IN  EFI_DEVICE_PATH_PROTOCOL  *ExclusiveDevicePath
 505   );
 506
 507 /**
 508   Connect the console device base on the variable ConVarName, if
 509   device path of the ConVarName is multi-instance device path, if
 510   anyone of the instances is connected success, then this function
 511   will return success.
 512
 513   @param  ConVarName               Console related variable name, ConIn, ConOut,
 514                                    ErrOut.
 515
 516   @retval EFI_NOT_FOUND            There is not any console devices connected
 517                                    success
 518   @retval EFI_SUCCESS              Success connect any one instance of the console
 519                                    device path base on the variable ConVarName.
 520
 521 **/
 522 EFI_STATUS
 523 EFIAPI
 524 BdsLibConnectConsoleVariable (
 525   IN  CHAR16                 *ConVarName
 526   );
 527
 528 //
 529 // Bds device path related lib functions
 530 //
 531 /**
 532   Delete the instance in Multi which matches partly with Single instance
 533
 534   @param  Multi                 A pointer to a multi-instance device path data
 535                                 structure.
 536   @param  Single                A pointer to a single-instance device path data
 537                                 structure.
 538
 539   @return This function will remove the device path instances in Multi which partly
 540           match with the Single, and return the result device path. If there is no
 541           remaining device path as a result, this function will return NULL.
 542
 543 **/
 544 EFI_DEVICE_PATH_PROTOCOL *
 545 EFIAPI
 546 BdsLibDelPartMatchInstance (
 547   IN     EFI_DEVICE_PATH_PROTOCOL  *Multi,
 548   IN     EFI_DEVICE_PATH_PROTOCOL  *Single
 549   );
 550
 551 /**
 552   Function compares a device path data structure to that of all the nodes of a
 553   second device path instance.
 554
 555   @param  Multi                 A pointer to a multi-instance device path data
 556                                 structure.
 557   @param  Single                A pointer to a single-instance device path data
 558                                 structure.
 559
 560   @retval TRUE                  If the Single device path is contained within Multi device path.
 561   @retval FALSE                 The Single device path is not match within Multi device path.
 562
 563 **/
 564 BOOLEAN
 565 EFIAPI
 566 BdsLibMatchDevicePaths (
 567   IN  EFI_DEVICE_PATH_PROTOCOL  *Multi,
 568   IN  EFI_DEVICE_PATH_PROTOCOL  *Single
 569   );
 570
 571 /**
 572   This function converts an input device structure to a Unicode string.
 573
 574   @param DevPath                  A pointer to the device path structure.
 575
 576   @return A new allocated Unicode string that represents the device path.
 577
 578 **/
 579 CHAR16 *
 580 EFIAPI
 581 DevicePathToStr (
 582   IN EFI_DEVICE_PATH_PROTOCOL     *DevPath
 583   );
 584
 585
 586 //
 587 // Internal definitions
 588 //
 589 typedef struct {
 590   CHAR16  *Str;
 591   UINTN   Len;
 592   UINTN   Maxlen;
 593 } POOL_PRINT;
 594
 595 typedef struct {
 596   UINT8 Type;
 597   UINT8 SubType;
 598   VOID (*Function) (POOL_PRINT *, VOID *);
 599 } DEVICE_PATH_STRING_TABLE;
 600
 601 extern EFI_GUID mEfiDevicePathMessagingUartFlowControlGuid;
 602
 603 typedef struct {
 604   EFI_DEVICE_PATH_PROTOCOL  Header;
 605   EFI_GUID                  Guid;
 606   UINT8                     VendorDefinedData[1];
 607 } VENDOR_DEVICE_PATH_WITH_DATA;
 608
 609
 610 extern EFI_GUID mEfiDevicePathMessagingSASGuid;
 611
 612 typedef struct {
 613   EFI_DEVICE_PATH_PROTOCOL  Header;
 614   UINT16                    NetworkProtocol;
 615   UINT16                    LoginOption;
 616   UINT64                    Lun;
 617   UINT16                    TargetPortalGroupTag;
 618   CHAR16                    TargetName[1];
 619 } ISCSI_DEVICE_PATH_WITH_NAME;
 620
 621
 622 //
 623 // Notes: EFI 64 shadow all option rom
 624 //
 625 #if defined (MDE_CPU_IPF)
 626 #define EFI64_SHADOW_ALL_LEGACY_ROM() ShadowAllOptionRom ();
 627 #else
 628 #define EFI64_SHADOW_ALL_LEGACY_ROM()
 629 #endif
 630
 631 /**
 632   Shadow all Legacy OptionRom.
 633
 634 **/
 635 VOID
 636 EFIAPI
 637 ShadowAllOptionRom (
 638   VOID
 639   );
 640
 641 //
 642 // BBS support macros and functions
 643 //
 644
 645 #if defined(MDE_CPU_IA32) || defined(MDE_CPU_X64)
 646 #define REFRESH_LEGACY_BOOT_OPTIONS \
 647         BdsDeleteAllInvalidLegacyBootOptions ();\
 648         BdsAddNonExistingLegacyBootOptions (); \
 649         BdsUpdateLegacyDevOrder ()
 650 #else
 651 #define REFRESH_LEGACY_BOOT_OPTIONS
 652 #endif
 653
 654 /**
 655   Delete all the invalid legacy boot options.
 656
 657   @retval EFI_SUCCESS             All invalide legacy boot options are deleted.
 658   @retval EFI_OUT_OF_RESOURCES    Fail to allocate necessary memory.
 659   @retval EFI_NOT_FOUND           Fail to retrive variable of boot order.
 660
 661 **/
 662 EFI_STATUS
 663 EFIAPI
 664 BdsDeleteAllInvalidLegacyBootOptions (
 665   VOID
 666   );
 667
 668 /**
 669
 670   Add the legacy boot options from BBS table if they do not exist.
 671
 672   @retval EFI_SUCCESS       The boot options are added successfully
 673                             or they are already in boot options.
 674
 675 **/
 676 EFI_STATUS
 677 EFIAPI
 678 BdsAddNonExistingLegacyBootOptions (
 679   VOID
 680   );
 681
 682 /**
 683
 684   Add the legacy boot devices from BBS table into
 685   the legacy device boot order.
 686
 687   @retval EFI_SUCCESS       The boot devices are added successfully.
 688
 689 **/
 690 EFI_STATUS
 691 EFIAPI
 692 BdsUpdateLegacyDevOrder (
 693   VOID
 694   );
 695
 696 /**
 697
 698   Set the boot priority for BBS entries based on boot option entry and boot order.
 699
 700   @param  Entry             The boot option is to be checked for refresh BBS table.
 701
 702   @retval EFI_SUCCESS       The boot priority for BBS entries is refreshed successfully.
 703
 704 **/
 705 EFI_STATUS
 706 EFIAPI
 707 BdsRefreshBbsTableForBoot (
 708   IN BDS_COMMON_OPTION        *Entry
 709   );
 710
 711 /**
 712
 713   Delete boot option specified by OptionNumber and adjust the boot order.
 714
 715   @param  OptionNumber      The boot option to be deleted.
 716   @param  BootOrder         Boot order list to be adjusted by remove this boot option.
 717   @param  BootOrderSize     The size of Boot order list will be modified.
 718
 719   @retval EFI_SUCCESS       The boot option is deleted successfully.
 720
 721 **/
 722 EFI_STATUS
 723 EFIAPI
 724 BdsDeleteBootOption (
 725   IN UINTN                       OptionNumber,
 726   IN OUT UINT16                  *BootOrder,
 727   IN OUT UINTN                   *BootOrderSize
 728   );
 729
 730 //
 731 //The interface functions relate with Setup Browser Reset Reminder feature
 732 //
 733 /**
 734   Enable the setup browser reset reminder feature.
 735   This routine is used in platform tip. If the platform policy need the feature, use the routine to enable it.
 736
 737 **/
 738 VOID
 739 EFIAPI
 740 EnableResetReminderFeature (
 741   VOID
 742   );
 743
 744 /**
 745   Disable the setup browser reset reminder feature.
 746   This routine is used in platform tip. If the platform policy do not want the feature, use the routine to disable it.
 747
 748 **/
 749 VOID
 750 EFIAPI
 751 DisableResetReminderFeature (
 752   VOID
 753   );
 754
 755 /**
 756   Record the info that  a reset is required.
 757   A  module boolean variable is used to record whether a reset is required.
 758
 759 **/
 760 VOID
 761 EFIAPI
 762 EnableResetRequired (
 763   VOID
 764   );
 765
 766
 767 /**
 768   Record the info that  no reset is required.
 769   A  module boolean variable is used to record whether a reset is required.
 770
 771 **/
 772 VOID
 773 EFIAPI
 774 DisableResetRequired (
 775   VOID
 776   );
 777
 778 /**
 779   Check whether platform policy enable the reset reminder feature. The default is enabled.
 780
 781 **/
 782 BOOLEAN
 783 EFIAPI
 784 IsResetReminderFeatureEnable (
 785   VOID
 786   );
 787
 788 /**
 789   Check if  user changed any option setting which needs a system reset to be effective.
 790
 791 **/
 792 BOOLEAN
 793 EFIAPI
 794 IsResetRequired (
 795   VOID
 796   );
 797
 798 /**
 799   Check whether a reset is needed, and finish the reset reminder feature.
 800   If a reset is needed, Popup a menu to notice user, and finish the feature
 801   according to the user selection.
 802
 803 **/
 804 VOID
 805 EFIAPI
 806 SetupResetReminder (
 807   VOID
 808   );
 809
 810
 811 //
 812 // Define the boot option default description
 813 // NOTE: This is not defined in UEFI spec.
 814 //
 815 #define DESCRIPTION_FLOPPY        L"EFI Floppy"
 816 #define DESCRIPTION_FLOPPY_NUM    L"EFI Floppy %d"
 817 #define DESCRIPTION_DVD           L"EFI DVD/CDROM"
 818 #define DESCRIPTION_DVD_NUM       L"EFI DVD/CDROM %d"
 819 #define DESCRIPTION_USB           L"EFI USB Device"
 820 #define DESCRIPTION_USB_NUM       L"EFI USB Device %d"
 821 #define DESCRIPTION_SCSI          L"EFI SCSI Device"
 822 #define DESCRIPTION_SCSI_NUM      L"EFI SCSI Device %d"
 823 #define DESCRIPTION_MISC          L"EFI Misc Device"
 824 #define DESCRIPTION_MISC_NUM      L"EFI Misc Device %d"
 825 #define DESCRIPTION_NETWORK       L"EFI Network"
 826 #define DESCRIPTION_NETWORK_NUM   L"EFI Network %d"
 827 #define DESCRIPTION_NON_BLOCK     L"EFI Non-Block Boot Device"
 828 #define DESCRIPTION_NON_BLOCK_NUM L"EFI Non-Block Boot Device %d"
 829
 830 //
 831 // Define the boot type which to classify the boot option type
 832 // Different boot option type could have different boot behavior
 833 // Use their device path node (Type + SubType) as type value
 834 // The boot type here can be added according to requirement
 835 //
 836 //
 837 // ACPI boot type. For ACPI device, cannot use sub-type to distinguish device, so hardcode their value
 838 //
 839 #define  BDS_EFI_ACPI_FLOPPY_BOOT         0x0201
 840 //
 841 // Message boot type
 842 // If a device path of boot option only point to a message node, the boot option is message boot type
 843 //
 844 #define  BDS_EFI_MESSAGE_ATAPI_BOOT       0x0301 // Type 03; Sub-Type 01
 845 #define  BDS_EFI_MESSAGE_SCSI_BOOT        0x0302 // Type 03; Sub-Type 02
 846 #define  BDS_EFI_MESSAGE_USB_DEVICE_BOOT  0x0305 // Type 03; Sub-Type 05
 847 #define  BDS_EFI_MESSAGE_SATA_BOOT        0x0318 // Type 03; Sub-Type 18
 848 #define  BDS_EFI_MESSAGE_MISC_BOOT        0x03FF
 849 //
 850 // Media boot type
 851 // If a device path of boot option contain a media node, the boot option is media boot type
 852 //
 853 #define  BDS_EFI_MEDIA_HD_BOOT            0x0401 // Type 04; Sub-Type 01
 854 #define  BDS_EFI_MEDIA_CDROM_BOOT         0x0402 // Type 04; Sub-Type 02
 855 //
 856 // BBS boot type
 857 // If a device path of boot option contain a BBS node, the boot option is BBS boot type
 858 //
 859 #define  BDS_LEGACY_BBS_BOOT              0x0501 //  Type 05; Sub-Type 01
 860
 861 #define  BDS_EFI_UNSUPPORT                0xFFFF
 862
 863 //
 864 // USB host controller Programming Interface.
 865 //
 866 #define  PCI_CLASSC_PI_UHCI               0x00
 867 #define  PCI_CLASSC_PI_EHCI               0x20
 868
 869 /**
 870   Check whether there is a instance in BlockIoDevicePath, which contain multi device path
 871   instances, has the same partition node with HardDriveDevicePath device path
 872
 873   @param  BlockIoDevicePath      Multi device path instances which need to check
 874   @param  HardDriveDevicePath    A device path which starts with a hard drive media
 875                                  device path.
 876
 877   @retval TRUE                   There is a matched device path instance.
 878   @retval FALSE                  There is no matched device path instance.
 879
 880 **/
 881 BOOLEAN
 882 EFIAPI
 883 MatchPartitionDevicePathNode (
 884   IN  EFI_DEVICE_PATH_PROTOCOL   *BlockIoDevicePath,
 885   IN  HARDDRIVE_DEVICE_PATH      *HardDriveDevicePath
 886   );
 887
 888
 889 /**
 890   Expand a device path that starts with a hard drive media device path node to be a
 891   full device path that includes the full hardware path to the device. We need
 892   to do this so it can be booted. As an optimizaiton the front match (the part point
 893   to the partition node. E.g. ACPI() /PCI()/ATA()/Partition() ) is saved in a variable
 894   so a connect all is not required on every boot. All successful history device path
 895   which point to partition node (the front part) will be saved.
 896
 897   @param  HardDriveDevicePath    EFI Device Path to boot, if it starts with a hard
 898                                  drive media device path.
 899   @return A Pointer to the full device path or NULL if a valid Hard Drive devic path
 900           cannot be found.
 901
 902 **/
 903 EFI_DEVICE_PATH_PROTOCOL *
 904 EFIAPI
 905 BdsExpandPartitionPartialDevicePathToFull (
 906   IN  HARDDRIVE_DEVICE_PATH      *HardDriveDevicePath
 907   );
 908
 909 /**
 910   Return the bootable media handle.
 911   First, check the device is connected
 912   Second, check whether the device path point to a device which support SimpleFileSystemProtocol,
 913   Third, detect the the default boot file in the Media, and return the removable Media handle.
 914
 915   @param  DevicePath             Device Path to a  bootable device
 916
 917   @retval NULL                   The media on the DevicePath is not bootable
 918
 919 **/
 920 EFI_HANDLE
 921 EFIAPI
 922 BdsLibGetBootableHandle (
 923   IN  EFI_DEVICE_PATH_PROTOCOL      *DevicePath
 924   );
 925
 926
 927 /**
 928   Check whether the Device path in a boot option point to a valide bootable device,
 929   And if CheckMedia is true, check the device is ready to boot now.
 930
 931   @param  DevPath     the Device path in a boot option
 932   @param  CheckMedia  if true, check the device is ready to boot now.
 933
 934   @retval TRUE        the Device path  is valide
 935   @retval FALSE       the Device path  is invalide .
 936
 937 **/
 938 BOOLEAN
 939 EFIAPI
 940 BdsLibIsValidEFIBootOptDevicePath (
 941   IN EFI_DEVICE_PATH_PROTOCOL     *DevPath,
 942   IN BOOLEAN                      CheckMedia
 943   );
 944
 945 /**
 946   Check whether the Device path in a boot option point to a valid bootable device,
 947   And if CheckMedia is true, check the device is ready to boot now.
 948   If Description is not NULL and the device path point to a fixed BlockIo
 949   device, check the description whether conflict with other auto-created
 950   boot options.
 951
 952   @param  DevPath     the Device path in a boot option
 953   @param  CheckMedia  if true, check the device is ready to boot now.
 954   @param  Description the description in a boot option
 955
 956   @retval TRUE        the Device path  is valid
 957   @retval FALSE       the Device path  is invalid .
 958
 959 **/
 960 BOOLEAN
 961 EFIAPI
 962 BdsLibIsValidEFIBootOptDevicePathExt (
 963   IN EFI_DEVICE_PATH_PROTOCOL     *DevPath,
 964   IN BOOLEAN                      CheckMedia,
 965   IN CHAR16                       *Description
 966   );
 967
 968 /**
 969   For a bootable Device path, return its boot type.
 970
 971   @param  DevicePath                      The bootable device Path to check
 972
 973   @retval BDS_EFI_MEDIA_HD_BOOT           If the device path contains any media deviec path node, it is media boot type
 974                                           For the floppy node, handle it as media node
 975   @retval BDS_EFI_MEDIA_CDROM_BOOT        If the device path contains any media deviec path node, it is media boot type
 976                                           For the floppy node, handle it as media node
 977   @retval BDS_EFI_ACPI_FLOPPY_BOOT        If the device path contains any media deviec path node, it is media boot type
 978                                           For the floppy node, handle it as media node
 979   @retval BDS_EFI_MESSAGE_ATAPI_BOOT      If the device path not contains any media deviec path node,  and
 980                                           its last device path node point to a message device path node, it is
 981
 982   @retval BDS_EFI_MESSAGE_SCSI_BOOT       If the device path not contains any media deviec path node,  and
 983                                           its last device path node point to a message device path node, it is
 984   @retval BDS_EFI_MESSAGE_USB_DEVICE_BOOT If the device path not contains any media deviec path node,  and
 985                                           its last device path node point to a message device path node, it is
 986   @retval BDS_EFI_MESSAGE_MISC_BOOT       If the device path not contains any media deviec path node,  and
 987                                           its last device path node point to a message device path node, it is
 988   @retval BDS_LEGACY_BBS_BOOT             Legacy boot type
 989   @retval BDS_EFI_UNSUPPORT               An EFI Removable BlockIO device path not point to a media and message devie,
 990
 991 **/
 992 UINT32
 993 EFIAPI
 994 BdsGetBootTypeFromDevicePath (
 995   IN  EFI_DEVICE_PATH_PROTOCOL     *DevicePath
 996   );
 997
 998
 999 /**
1000   This routine register a function to adjust the different type memory page number
1001   just before booting and save the updated info into the variable for next boot to use.
1002
1003 **/
1004 VOID
1005 EFIAPI
1006 BdsLibSaveMemoryTypeInformation (
1007   VOID
1008   );
1009
1010
1011 /**
1012   According to a file guild, check a Fv file device path is valid. If it is invalid,
1013   try to return the valid device path.
1014   FV address maybe changes for memory layout adjust from time to time, use this funciton
1015   could promise the Fv file device path is right.
1016
1017   @param  DevicePath             on input, the Fv file device path need to check on
1018                                  output, the updated valid Fv file device path
1019   @param  FileGuid               the Fv file guild
1020
1021   @retval EFI_INVALID_PARAMETER  the input DevicePath or FileGuid is invalid
1022                                  parameter
1023   @retval EFI_UNSUPPORTED        the input DevicePath does not contain Fv file
1024                                  guild at all
1025   @retval EFI_ALREADY_STARTED    the input DevicePath has pointed to Fv file, it is
1026                                  valid
1027   @retval EFI_SUCCESS            has successfully updated the invalid DevicePath,
1028                                  and return the updated device path in DevicePath
1029
1030 **/
1031 EFI_STATUS
1032 EFIAPI
1033 BdsLibUpdateFvFileDevicePath (
1034   IN  OUT EFI_DEVICE_PATH_PROTOCOL      ** DevicePath,
1035   IN  EFI_GUID                          *FileGuid
1036   );
1037
1038
1039 /**
1040   Connect the specific Usb device which match the short form device path,
1041   and whose bus is determined by Host Controller (Uhci or Ehci)
1042
1043   @param  HostControllerPI      Uhci (0x00) or Ehci (0x20) or Both uhci and ehci
1044                                 (0xFF)
1045   @param  RemainingDevicePath   a short-form device path that starts with the first
1046                                 element being a USB WWID or a USB Class device
1047                                 path
1048
1049   @retval EFI_SUCCESS           The specific Usb device is connected successfully.
1050   @retval EFI_INVALID_PARAMETER Invalid HostControllerPi (not 0x00, 0x20 or 0xFF)
1051                                 or RemainingDevicePath is not the USB class device path.
1052   @retval EFI_NOT_FOUND         The device specified by device path is not found.
1053
1054 **/
1055 EFI_STATUS
1056 EFIAPI
1057 BdsLibConnectUsbDevByShortFormDP(
1058   IN UINT8                      HostControllerPI,
1059   IN EFI_DEVICE_PATH_PROTOCOL   *RemainingDevicePath
1060   );
1061
1062
1063 //
1064 // The implementation of this function is provided by Platform code.
1065 //
1066 /**
1067   Convert Vendor device path to device name.
1068
1069   @param  Str      The buffer store device name
1070   @param  DevPath  Pointer to vendor device path
1071
1072 **/
1073 VOID
1074 DevPathVendor (
1075   IN OUT POOL_PRINT       *Str,
1076   IN VOID                 *DevPath
1077   );
1078
1079 /**
1080   Concatenates a formatted unicode string to allocated pool.
1081   The caller must free the resulting buffer.
1082
1083   @param  Str      Tracks the allocated pool, size in use, and amount of pool allocated.
1084   @param  Fmt      The format string
1085   @param  ...      The data will be printed.
1086
1087   @return Allocated buffer with the formatted string printed in it.
1088           The caller must free the allocated buffer.
1089           The buffer allocation is not packed.
1090
1091 **/
1092 CHAR16 *
1093 EFIAPI
1094 CatPrint (
1095   IN OUT POOL_PRINT   *Str,
1096   IN CHAR16           *Fmt,
1097   ...
1098   );
1099
1100 /**
1101   Use Console Control to turn off UGA based Simple Text Out consoles from going
1102   to the UGA device. Put up LogoFile on every UGA device that is a console
1103
1104   @param[in]  LogoFile   File name of logo to display on the center of the screen.
1105
1106   @retval EFI_SUCCESS     ConsoleControl has been flipped to graphics and logo displayed.
1107   @retval EFI_UNSUPPORTED Logo not found
1108
1109 **/
1110 EFI_STATUS
1111 EFIAPI
1112 EnableQuietBoot (
1113   IN  EFI_GUID  *LogoFile
1114   );
1115
1116
1117 /**
1118   Use Console Control to turn on UGA based Simple Text Out consoles. The UGA
1119   Simple Text Out screens will now be synced up with all non UGA output devices
1120
1121   @retval EFI_SUCCESS     UGA devices are back in text mode and synced up.
1122
1123 **/
1124 EFI_STATUS
1125 EFIAPI
1126 DisableQuietBoot (
1127   VOID
1128   );
1129
1130 /**
1131   Use Console Control Protocol to lock the Console In Spliter virtual handle.
1132   This is the ConInHandle and ConIn handle in the EFI system table. All key
1133   presses will be ignored until the Password is typed in. The only way to
1134   disable the password is to type it in to a ConIn device.
1135
1136   @param  Password        Password used to lock ConIn device.
1137
1138   @retval EFI_SUCCESS     lock the Console In Spliter virtual handle successfully.
1139   @retval EFI_UNSUPPORTED Password not found
1140
1141 **/
1142 EFI_STATUS
1143 EFIAPI
1144 LockKeyboards (
1145   IN  CHAR16    *Password
1146   );
1147
1148 #endif
1149