ae01b3f602e7ea9579f1482a5e2ff9bb9eae85db
[mirror_edk2.git] / IntelFrameworkModulePkg / Universal / BdsDxe / DeviceMngr / DeviceManager.h
1 /** @file
2 The platform device manager reference implement
3
4 Copyright (c) 2004 - 2011, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 **/
14
15 #ifndef _DEVICE_MANAGER_H_
16 #define _DEVICE_MANAGER_H_
17
18 #include "Bds.h"
19 #include "FrontPage.h"
20 #include "DeviceManagerVfr.h"
21 #include <Protocol/PciIo.h>
22
23 #define DEVICE_MANAGER_CALLBACK_DATA_SIGNATURE SIGNATURE_32 ('D', 'M', 'C', 'B')
24 #define DEVICE_MANAGER_DRIVER_HEALTH_INFO_SIGNATURE SIGNATURE_32 ('D', 'M', 'D', 'H')
25
26
27 typedef struct {
28 UINTN Signature;
29
30 ///
31 /// Device Manager HII relative handles
32 ///
33 EFI_HII_HANDLE HiiHandle;
34
35 ///
36 /// Driver Health HII relative handles
37 ///
38 EFI_HII_HANDLE DriverHealthHiiHandle;
39
40 EFI_HANDLE DriverHandle;
41 EFI_HANDLE DriverHealthHandle;
42
43 ///
44 /// Device Manager Produced protocols
45 ///
46 EFI_HII_CONFIG_ACCESS_PROTOCOL ConfigAccess;
47
48 ///
49 /// Driver Health Produced protocols
50 ///
51 EFI_HII_CONFIG_ACCESS_PROTOCOL DriverHealthConfigAccess;
52
53 ///
54 /// Configuration data
55 ///
56 UINT8 VideoBios;
57 } DEVICE_MANAGER_CALLBACK_DATA;
58
59
60 typedef struct {
61 UINTN Signature;
62 LIST_ENTRY Link;
63
64 ///
65 /// HII relative handles
66 ///
67 EFI_HII_HANDLE HiiHandle;
68
69 ///
70 /// Driver relative handles
71 ///
72 EFI_HANDLE DriverHandle;
73 EFI_HANDLE ControllerHandle;
74 EFI_HANDLE ChildHandle;
75
76 EFI_DRIVER_HEALTH_PROTOCOL *DriverHealth;
77 ///
78 /// Driver health messages of the specify Driver
79 ///
80 EFI_DRIVER_HEALTH_HII_MESSAGE *MessageList;
81
82 ///
83 /// Driver Health status
84 ///
85 EFI_DRIVER_HEALTH_STATUS HealthStatus;
86 } DRIVER_HEALTH_INFO;
87
88 typedef struct {
89 EFI_STRING_ID PromptId;
90 EFI_QUESTION_ID QuestionId;
91 }MENU_INFO_ITEM;
92
93 typedef struct {
94 UINTN CurListLen;
95 UINTN MaxListLen;
96 MENU_INFO_ITEM *NodeList;
97 } MAC_ADDRESS_NODE_LIST;
98
99 #define DEVICE_MANAGER_HEALTH_INFO_FROM_LINK(a) \
100 CR (a, \
101 DRIVER_HEALTH_INFO, \
102 Link, \
103 DEVICE_MANAGER_DRIVER_HEALTH_INFO_SIGNATURE \
104 )
105
106 #define DEVICE_MANAGER_CALLBACK_DATA_FROM_THIS(a) \
107 CR (a, \
108 DEVICE_MANAGER_CALLBACK_DATA, \
109 ConfigAccess, \
110 DEVICE_MANAGER_CALLBACK_DATA_SIGNATURE \
111 )
112 typedef struct {
113 EFI_STRING_ID StringId;
114 UINT16 Class;
115 } DEVICE_MANAGER_MENU_ITEM;
116
117 /**
118 This function is invoked if user selected a interactive opcode from Device Manager's
119 Formset. The decision by user is saved to gCallbackKey for later processing. If
120 user set VBIOS, the new value is saved to EFI variable.
121
122
123 @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
124 @param Action Specifies the type of action taken by the browser.
125 @param QuestionId A unique value which is sent to the original exporting driver
126 so that it can identify the type of data to expect.
127 @param Type The type of value for the question.
128 @param Value A pointer to the data being sent to the original exporting driver.
129 @param ActionRequest On return, points to the action requested by the callback function.
130
131 @retval EFI_SUCCESS The callback successfully handled the action.
132 @retval EFI_INVALID_PARAMETER The setup browser call this function with invalid parameters.
133
134 **/
135 EFI_STATUS
136 EFIAPI
137 DeviceManagerCallback (
138 IN CONST EFI_HII_CONFIG_ACCESS_PROTOCOL *This,
139 IN EFI_BROWSER_ACTION Action,
140 IN EFI_QUESTION_ID QuestionId,
141 IN UINT8 Type,
142 IN EFI_IFR_TYPE_VALUE *Value,
143 OUT EFI_BROWSER_ACTION_REQUEST *ActionRequest
144 );
145
146 /**
147 This function is invoked if user selected a interactive opcode from Driver Health's
148 Formset. The decision by user is saved to gCallbackKey for later processing.
149
150
151 @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
152 @param Action Specifies the type of action taken by the browser.
153 @param QuestionId A unique value which is sent to the original exporting driver
154 so that it can identify the type of data to expect.
155 @param Type The type of value for the question.
156 @param Value A pointer to the data being sent to the original exporting driver.
157 @param ActionRequest On return, points to the action requested by the callback function.
158
159 @retval EFI_SUCCESS The callback successfully handled the action.
160 @retval EFI_INVALID_PARAMETER The setup browser call this function with invalid parameters.
161
162 **/
163 EFI_STATUS
164 EFIAPI
165 DriverHealthCallback (
166 IN CONST EFI_HII_CONFIG_ACCESS_PROTOCOL *This,
167 IN EFI_BROWSER_ACTION Action,
168 IN EFI_QUESTION_ID QuestionId,
169 IN UINT8 Type,
170 IN EFI_IFR_TYPE_VALUE *Value,
171 OUT EFI_BROWSER_ACTION_REQUEST *ActionRequest
172 );
173
174
175 /**
176
177 This function registers HII packages to HII database.
178
179 @retval EFI_SUCCESS HII packages for the Device Manager were registered successfully.
180 @retval EFI_OUT_OF_RESOURCES HII packages for the Device Manager failed to be registered.
181
182 **/
183 EFI_STATUS
184 InitializeDeviceManager (
185 VOID
186 );
187
188 /**
189
190 Call the browser and display the device manager to allow user
191 to configure the platform.
192
193 This function create the dynamic content for device manager. It includes
194 section header for all class of devices, one-of opcode to set VBIOS.
195
196 @retval EFI_SUCCESS Operation is successful.
197 @retval Other values if failed to clean up the dynamic content from HII
198 database.
199
200 **/
201 EFI_STATUS
202 CallDeviceManager (
203 VOID
204 );
205
206
207 /**
208 Check the Driver Health status of a single controller and try to process it if not healthy.
209
210 This function called by CheckAllControllersHealthStatus () function in order to process a specify
211 contoller's health state.
212
213 @param DriverHealthList A Pointer to the list contain all of the platform driver health information.
214 @param DriverHandle The handle of driver.
215 @param ControllerHandle The class guid specifies which form set will be displayed.
216 @param ChildHandle The handle of the child controller to retrieve the health
217 status on. This is an optional parameter that may be NULL.
218 @param DriverHealth A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
219 @param HealthStatus The health status of the controller.
220
221 @retval EFI_INVALID_PARAMETER HealthStatus or DriverHealth is NULL.
222 @retval HealthStatus The Health status of specify controller.
223 @retval EFI_OUT_OF_RESOURCES The list of Driver Health Protocol handles can not be retrieved.
224 @retval EFI_NOT_FOUND No controller in the platform install Driver Health Protocol.
225 @retval EFI_SUCCESS The Health related operation has been taken successfully.
226
227 **/
228 EFI_STATUS
229 EFIAPI
230 GetSingleControllerHealthStatus (
231 IN OUT LIST_ENTRY *DriverHealthList,
232 IN EFI_HANDLE DriverHandle,
233 IN EFI_HANDLE ControllerHandle, OPTIONAL
234 IN EFI_HANDLE ChildHandle, OPTIONAL
235 IN EFI_DRIVER_HEALTH_PROTOCOL *DriverHealth,
236 IN EFI_DRIVER_HEALTH_STATUS *HealthStatus
237 );
238
239 /**
240 Collects all the EFI Driver Health Protocols currently present in the EFI Handle Database,
241 and queries each EFI Driver Health Protocol to determine if one or more of the controllers
242 managed by each EFI Driver Health Protocol instance are not healthy.
243
244 @param DriverHealthList A Pointer to the list contain all of the platform driver health
245 information.
246
247 @retval EFI_NOT_FOUND No controller in the platform install Driver Health Protocol.
248 @retval EFI_SUCCESS All the controllers in the platform are healthy.
249 @retval EFI_OUT_OF_RESOURCES The list of Driver Health Protocol handles can not be retrieved.
250
251 **/
252 EFI_STATUS
253 GetAllControllersHealthStatus (
254 IN OUT LIST_ENTRY *DriverHealthList
255 );
256
257 /**
258 Check the healthy status of the platform, this function will return immediately while found one driver
259 in the platform are not healthy.
260
261 @retval FALSE at least one driver in the platform are not healthy.
262 @retval TRUE No controller install Driver Health Protocol,
263 or all controllers in the platform are in healthy status.
264 **/
265 BOOLEAN
266 PlaformHealthStatusCheck (
267 VOID
268 );
269
270 /**
271 Repair the whole platform.
272
273 This function is the main entry for user choose "Repair All" in the front page.
274 It will try to do recovery job till all the driver health protocol installed modules
275 reach a terminal state.
276
277 @param DriverHealthList A Pointer to the list contain all of the platform driver health
278 information.
279
280 **/
281 VOID
282 PlatformRepairAll (
283 IN LIST_ENTRY *DriverHealthList
284 );
285
286 /**
287 Processes a single controller using the EFI Driver Health Protocol associated with
288 that controller. This algorithm continues to query the GetHealthStatus() service until
289 one of the legal terminal states of the EFI Driver Health Protocol is reached. This may
290 require the processing of HII Messages, HII Form, and invocation of repair operations.
291
292 @param DriverHealth A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
293 @param ControllerHandle The class guid specifies which form set will be displayed.
294 @param ChildHandle The handle of the child controller to retrieve the health
295 status on. This is an optional parameter that may be NULL.
296 @param HealthStatus The health status of the controller.
297 @param MessageList An array of warning or error messages associated
298 with the controller specified by ControllerHandle and
299 ChildHandle. This is an optional parameter that may be NULL.
300 @param FormHiiHandle The HII handle for an HII form associated with the
301 controller specified by ControllerHandle and ChildHandle.
302 @param RebootRequired Indicate whether a reboot is required to repair the controller.
303 **/
304 VOID
305 ProcessSingleControllerHealth (
306 IN EFI_DRIVER_HEALTH_PROTOCOL *DriverHealth,
307 IN EFI_HANDLE ControllerHandle, OPTIONAL
308 IN EFI_HANDLE ChildHandle, OPTIONAL
309 IN EFI_DRIVER_HEALTH_STATUS HealthStatus,
310 IN EFI_DRIVER_HEALTH_HII_MESSAGE **MessageList, OPTIONAL
311 IN EFI_HII_HANDLE FormHiiHandle,
312 IN OUT BOOLEAN *RebootRequired
313 );
314
315 /**
316 Repair notification function, simply print the repair progress.
317
318 @param Value The value of part has been repaired.
319 @param Limit Total value need to be repaired.
320
321 **/
322 VOID
323 RepairNotify (
324 IN UINTN Value,
325 IN UINTN Limit
326 );
327
328 /**
329 Processes a set of messages returned by the GetHealthStatus ()
330 service of the EFI Driver Health Protocol
331
332 @param MessageList The MessageList point to messages need to processed.
333
334 **/
335 VOID
336 ProcessMessages (
337 IN EFI_DRIVER_HEALTH_HII_MESSAGE *MessageList
338 );
339
340
341 /**
342 Collect and display the platform's driver health relative information, allow user to do interactive
343 operation while the platform is unhealthy.
344
345 This function display a form which divided into two parts. The one list all modules which has installed
346 driver health protocol. The list usually contain driver name, controller name, and it's health info.
347 While the driver name can't be retrieved, will use device path as backup. The other part of the form provide
348 a choice to the user to repair all platform.
349
350 **/
351 VOID
352 CallDriverHealth (
353 VOID
354 );
355
356 /**
357
358 Select the best matching language according to front page policy for best user experience.
359
360 This function supports both ISO 639-2 and RFC 4646 language codes, but language
361 code types may not be mixed in a single call to this function.
362
363 @param SupportedLanguages A pointer to a Null-terminated ASCII string that
364 contains a set of language codes in the format
365 specified by Iso639Language.
366 @param Iso639Language If TRUE, then all language codes are assumed to be
367 in ISO 639-2 format. If FALSE, then all language
368 codes are assumed to be in RFC 4646 language format.
369
370 @retval NULL The best matching language could not be found in SupportedLanguages.
371 @retval NULL There are not enough resources available to return the best matching
372 language.
373 @retval Other A pointer to a Null-terminated ASCII string that is the best matching
374 language in SupportedLanguages.
375 **/
376 CHAR8 *
377 DriverHealthSelectBestLanguage (
378 IN CHAR8 *SupportedLanguages,
379 IN BOOLEAN Iso639Language
380 );
381
382 /**
383
384 This is an internal worker function to get the Component Name (2) protocol interface
385 and the language it supports.
386
387 @param ProtocolGuid A pointer to an EFI_GUID. It points to Component Name (2) protocol GUID.
388 @param DriverBindingHandle The handle on which the Component Name (2) protocol instance is retrieved.
389 @param ComponentName A pointer to the Component Name (2) protocol interface.
390 @param SupportedLanguage The best suitable language that matches the SupportedLangues interface for the
391 located Component Name (2) instance.
392
393 @retval EFI_SUCCESS The Component Name (2) protocol instance is successfully located and we find
394 the best matching language it support.
395 @retval EFI_UNSUPPORTED The input Language is not supported by the Component Name (2) protocol.
396 @retval Other Some error occurs when locating Component Name (2) protocol instance or finding
397 the supported language.
398
399 **/
400 EFI_STATUS
401 GetComponentNameWorker (
402 IN EFI_GUID *ProtocolGuid,
403 IN EFI_HANDLE DriverBindingHandle,
404 OUT EFI_COMPONENT_NAME_PROTOCOL **ComponentName,
405 OUT CHAR8 **SupportedLanguage
406 );
407
408 /**
409
410 This is an internal worker function to get driver name from Component Name (2) protocol interface.
411
412
413 @param ProtocolGuid A pointer to an EFI_GUID. It points to Component Name (2) protocol GUID.
414 @param DriverBindingHandle The handle on which the Component Name (2) protocol instance is retrieved.
415 @param DriverName A pointer to the Unicode string to return. This Unicode string is the name
416 of the driver specified by This.
417
418 @retval EFI_SUCCESS The driver name is successfully retrieved from Component Name (2) protocol
419 interface.
420 @retval Other The driver name cannot be retrieved from Component Name (2) protocol
421 interface.
422
423 **/
424 EFI_STATUS
425 GetDriverNameWorker (
426 IN EFI_GUID *ProtocolGuid,
427 IN EFI_HANDLE DriverBindingHandle,
428 OUT CHAR16 **DriverName
429 );
430
431 /**
432
433 This function gets driver name from Component Name 2 protocol interface and Component Name protocol interface
434 in turn. It first tries UEFI 2.0 Component Name 2 protocol interface and try to get the driver name.
435 If the attempt fails, it then gets the driver name from EFI 1.1 Component Name protocol for backward
436 compatibility support.
437
438 @param DriverBindingHandle The handle on which the Component Name (2) protocol instance is retrieved.
439 @param DriverName A pointer to the Unicode string to return. This Unicode string is the name
440 of the driver specified by This.
441
442 @retval EFI_SUCCESS The driver name is successfully retrieved from Component Name (2) protocol
443 interface.
444 @retval Other The driver name cannot be retrieved from Component Name (2) protocol
445 interface.
446
447 **/
448 EFI_STATUS
449 DriverHealthGetDriverName (
450 IN EFI_HANDLE DriverBindingHandle,
451 OUT CHAR16 **DriverName
452 );
453
454 /**
455 This function gets controller name from Component Name 2 protocol interface and Component Name protocol interface
456 in turn. It first tries UEFI 2.0 Component Name 2 protocol interface and try to get the controller name.
457 If the attempt fails, it then gets the controller name from EFI 1.1 Component Name protocol for backward
458 compatibility support.
459
460 @param ProtocolGuid A pointer to an EFI_GUID. It points to Component Name (2) protocol GUID.
461 @param DriverBindingHandle The handle on which the Component Name (2) protocol instance is retrieved.
462 @param ControllerHandle The handle of a controller that the driver specified by This is managing.
463 This handle specifies the controller whose name is to be returned.
464 @param ChildHandle The handle of the child controller to retrieve the name of. This is an
465 optional parameter that may be NULL. It will be NULL for device drivers.
466 It will also be NULL for bus drivers that attempt to retrieve the name
467 of the bus controller. It will not be NULL for a bus driver that attempts
468 to retrieve the name of a child controller.
469 @param ControllerName A pointer to the Unicode string to return. This Unicode string
470 is the name of the controller specified by ControllerHandle and ChildHandle.
471
472 @retval EFI_SUCCESS The controller name is successfully retrieved from Component Name (2) protocol
473 interface.
474 @retval Other The controller name cannot be retrieved from Component Name (2) protocol.
475
476 **/
477 EFI_STATUS
478 GetControllerNameWorker (
479 IN EFI_GUID *ProtocolGuid,
480 IN EFI_HANDLE DriverBindingHandle,
481 IN EFI_HANDLE ControllerHandle,
482 IN EFI_HANDLE ChildHandle,
483 OUT CHAR16 **ControllerName
484 );
485
486 /**
487 This function gets controller name from Component Name 2 protocol interface and Component Name protocol interface
488 in turn. It first tries UEFI 2.0 Component Name 2 protocol interface and try to get the controller name.
489 If the attempt fails, it then gets the controller name from EFI 1.1 Component Name protocol for backward
490 compatibility support.
491
492 @param DriverBindingHandle The handle on which the Component Name (2) protocol instance is retrieved.
493 @param ControllerHandle The handle of a controller that the driver specified by This is managing.
494 This handle specifies the controller whose name is to be returned.
495 @param ChildHandle The handle of the child controller to retrieve the name of. This is an
496 optional parameter that may be NULL. It will be NULL for device drivers.
497 It will also be NULL for bus drivers that attempt to retrieve the name
498 of the bus controller. It will not be NULL for a bus driver that attempts
499 to retrieve the name of a child controller.
500 @param ControllerName A pointer to the Unicode string to return. This Unicode string
501 is the name of the controller specified by ControllerHandle and ChildHandle.
502
503 @retval EFI_SUCCESS The controller name is successfully retrieved from Component Name (2) protocol
504 interface.
505 @retval Other The controller name cannot be retrieved from Component Name (2) protocol.
506
507 **/
508 EFI_STATUS
509 DriverHealthGetControllerName (
510 IN EFI_HANDLE DriverBindingHandle,
511 IN EFI_HANDLE ControllerHandle,
512 IN EFI_HANDLE ChildHandle,
513 OUT CHAR16 **ControllerName
514 );
515
516 #endif