MdePkg: Add BootManagerPolicy protocol definition.
[mirror_edk2.git] / 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