MdePkg/Include/Protocol/BootManagerPolicy.h

   1 /** @file
   2   Boot Manager Policy Protocol as defined in UEFI Specification.
   3
   4   This protocol is used by EFI Applications to request the UEFI Boot Manager
   5   to connect devices using platform policy.
   6
   7   Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9 **/
  10
  11 #ifndef __BOOT_MANAGER_POLICY_H__
  12 #define __BOOT_MANAGER_POLICY_H__
  13
  14 #define EFI_BOOT_MANAGER_POLICY_PROTOCOL_GUID \
  15   { \
  16     0xFEDF8E0C, 0xE147, 0x11E3, { 0x99, 0x03, 0xB8, 0xE8, 0x56, 0x2C, 0xBA, 0xFA } \
  17   }
  18
  19 #define EFI_BOOT_MANAGER_POLICY_CONSOLE_GUID \
  20   { \
  21     0xCAB0E94C, 0xE15F, 0x11E3, { 0x91, 0x8D, 0xB8, 0xE8, 0x56, 0x2C, 0xBA, 0xFA } \
  22   }
  23
  24 #define EFI_BOOT_MANAGER_POLICY_NETWORK_GUID \
  25   { \
  26     0xD04159DC, 0xE15F, 0x11E3, { 0xB2, 0x61, 0xB8, 0xE8, 0x56, 0x2C, 0xBA, 0xFA } \
  27   }
  28
  29 #define EFI_BOOT_MANAGER_POLICY_CONNECT_ALL_GUID \
  30   { \
  31     0x113B2126, 0xFC8A, 0x11E3, { 0xBD, 0x6C, 0xB8, 0xE8, 0x56, 0x2C, 0xBA, 0xFA } \
  32   }
  33
  34 typedef struct _EFI_BOOT_MANAGER_POLICY_PROTOCOL EFI_BOOT_MANAGER_POLICY_PROTOCOL;
  35
  36 #define EFI_BOOT_MANAGER_POLICY_PROTOCOL_REVISION 0x00010000
  37
  38 /**
  39   Connect a device path following the platforms EFI Boot Manager policy.
  40
  41   The ConnectDevicePath() function allows the caller to connect a DevicePath using the
  42   same policy as the EFI Boot Manger.
  43
  44   @param[in] This       A pointer to the EFI_BOOT_MANAGER_POLICY_PROTOCOL instance.
  45   @param[in] DevicePath Points to the start of the EFI device path to connect.
  46                         If DevicePath is NULL then all the controllers in the
  47                         system will be connected using the platforms EFI Boot
  48                         Manager policy.
  49   @param[in] Recursive  If TRUE, then ConnectController() is called recursively
  50                         until the entire tree of controllers below the
  51                         controller specified by DevicePath have been created.
  52                         If FALSE, then the tree of controllers is only expanded
  53                         one level. If DevicePath is NULL then Recursive is ignored.
  54
  55   @retval EFI_SUCCESS            The DevicePath was connected.
  56   @retval EFI_NOT_FOUND          The DevicePath was not found.
  57   @retval EFI_NOT_FOUND          No driver was connected to DevicePath.
  58   @retval EFI_SECURITY_VIOLATION The user has no permission to start UEFI device
  59                                  drivers on the DevicePath.
  60   @retval EFI_UNSUPPORTED        The current TPL is not TPL_APPLICATION.
  61 **/
  62 typedef
  63 EFI_STATUS
  64 (EFIAPI *EFI_BOOT_MANAGER_POLICY_CONNECT_DEVICE_PATH)(
  65   IN EFI_BOOT_MANAGER_POLICY_PROTOCOL *This,
  66   IN EFI_DEVICE_PATH                  *DevicePath,
  67   IN BOOLEAN                          Recursive
  68   );
  69
  70 /**
  71   Connect a class of devices using the platform Boot Manager policy.
  72
  73   The ConnectDeviceClass() function allows the caller to request that the Boot
  74   Manager connect a class of devices.
  75
  76   If Class is EFI_BOOT_MANAGER_POLICY_CONSOLE_GUID then the Boot Manager will
  77   use platform policy to connect consoles. Some platforms may restrict the
  78   number of consoles connected as they attempt to fast boot, and calling
  79   ConnectDeviceClass() with a Class value of EFI_BOOT_MANAGER_POLICY_CONSOLE_GUID
  80   must connect the set of consoles that follow the Boot Manager platform policy,
  81   and the EFI_SIMPLE_TEXT_INPUT_PROTOCOL, EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL, and
  82   the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL are produced on the connected handles.
  83   The Boot Manager may restrict which consoles get connect due to platform policy,
  84   for example a security policy may require that a given console is not connected.
  85
  86   If Class is EFI_BOOT_MANAGER_POLICY_NETWORK_GUID then the Boot Manager will
  87   connect the protocols the platforms supports for UEFI general purpose network
  88   applications on one or more handles. If more than one network controller is
  89   available a platform will connect, one, many, or all of the networks based
  90   on platform policy. Connecting UEFI networking protocols, like EFI_DHCP4_PROTOCOL,
  91   does not establish connections on the network. The UEFI general purpose network
  92   application that called ConnectDeviceClass() may need to use the published
  93   protocols to establish the network connection. The Boot Manager can optionally
  94   have a policy to establish a network connection.
  95
  96   If Class is EFI_BOOT_MANAGER_POLICY_CONNECT_ALL_GUID then the Boot Manager
  97   will connect all UEFI drivers using the UEFI Boot Service
  98   EFI_BOOT_SERVICES.ConnectController(). If the Boot Manager has policy
  99   associated with connect all UEFI drivers this policy will be used.
 100
 101   A platform can also define platform specific Class values as a properly generated
 102   EFI_GUID would never conflict with this specification.
 103
 104   @param[in] This  A pointer to the EFI_BOOT_MANAGER_POLICY_PROTOCOL instance.
 105   @param[in] Class A pointer to an EFI_GUID that represents a class of devices
 106                    that will be connected using the Boot Mangers platform policy.
 107
 108   @retval EFI_SUCCESS      At least one devices of the Class was connected.
 109   @retval EFI_DEVICE_ERROR Devices were not connected due to an error.
 110   @retval EFI_NOT_FOUND    The Class is not supported by the platform.
 111   @retval EFI_UNSUPPORTED  The current TPL is not TPL_APPLICATION.
 112 **/
 113 typedef
 114 EFI_STATUS
 115 (EFIAPI *EFI_BOOT_MANAGER_POLICY_CONNECT_DEVICE_CLASS)(
 116   IN EFI_BOOT_MANAGER_POLICY_PROTOCOL *This,
 117   IN EFI_GUID                         *Class
 118   );
 119
 120 struct _EFI_BOOT_MANAGER_POLICY_PROTOCOL {
 121   UINT64                                       Revision;
 122   EFI_BOOT_MANAGER_POLICY_CONNECT_DEVICE_PATH  ConnectDevicePath;
 123   EFI_BOOT_MANAGER_POLICY_CONNECT_DEVICE_CLASS ConnectDeviceClass;
 124 };
 125
 126 extern EFI_GUID gEfiBootManagerPolicyProtocolGuid;
 127
 128 extern EFI_GUID gEfiBootManagerPolicyConsoleGuid;
 129 extern EFI_GUID gEfiBootManagerPolicyNetworkGuid;
 130 extern EFI_GUID gEfiBootManagerPolicyConnectAllGuid;
 131
 132 #endif