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