audk/MdePkg/Include/Protocol/DriverHealth.h

/** @file
  EFI Driver Health Protocol

  Copyright (c) 2006 - 2008, Intel Corporation                                                         
  All rights reserved. This program and the accompanying materials                          
  are licensed and made available under the terms and conditions of the BSD License         
  which accompanies this distribution.  The full text of the license may be found at        
  http://opensource.org/licenses/bsd-license.php                                            

  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             

**/

#ifndef __EFI_DRIVER_HEALTH_H__
#define __EFI_DRIVER_HEALTH_H__

#define EFI_DRIVER_HEALTH_PROTOCOL_GUID \
  { \
    0x2a534210, 0x9280, 0x41d8, { 0xae, 0x79, 0xca, 0xda, 0x1, 0xa2, 0xb1, 0x27 } \
  }
  
typedef struct _EFI_DRIVER_HEALTH_PROTOCOL  EFI_DRIVER_HEALTH_PROTOCOL;

///
/// EFI_DRIVER_HEALTH_HEALTH_STATUS
///
typedef enum {
  EfiDriverHealthStatusHealthy,
  EfiDriverHealthStatusRepairRequired,
  EfiDriverHealthStatusConfigurationRequired,
  EfiDriverHealthStatusFailed,
  EfiDriverHealthStatusReconnectRequired,
  EfiDriverHealthStatusRebootRequired
} EFI_DRIVER_HEALTH_HEALTH_STATUS;

///
/// EFI_DRIVER_HEALTH_HII_MESSAGE
///
typedef struct {
  EFI_HII_HANDLE  HiiHandle;
  EFI_STRING_ID   StringId;
  UINT64          Reserved;
} EFI_DRIVER_HEALTH_HII_MESSAGE;

/**
  Reports the progress of a repair operation

  @param  Value            A value between 0 and Limit that identifies the current 
                           progress of the repair operation.
  
  @param  Limit            The maximum value of Value for the current repair operation.
                           For example, a driver that wants to specify progress in 
                           percent would use a Limit value of 100.
**/
typedef
VOID
(EFIAPI *EFI_DRIVER_HEALTH_REPAIR_PROGRESS_NOTIFY)(
  IN UINTN  Value,
  IN UINTN  Limit
  );

/**
  Retrieves the health status of a controller in the platform.  This function can also 
  optionally return warning messages, error messages, and a set of HII Forms that may 
  be repair a controller that is not proper configured. 
  
  @param  This             A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.

  @param  ControllerHandle The handle of the controller to retrieve the health status 
                           on.  This is an optional parameter that may be NULL.  If 
                           this parameter is NULL, then the value of ChildHandle is 
                           ignored, and the combined health status of all the devices 
                           that the driver is managing is returned.

  @param  ChildHandle      The handle of the child controller to retrieve the health 
                           status on.  This is an optional parameter that may be NULL.  
                           This parameter is ignored of ControllerHandle is NULL.  It 
                           will be NULL for device drivers.  It will also be NULL for 
                           bus drivers when an attempt is made to collect the health 
                           status of the bus controller.  If will not be NULL when an 
                           attempt is made to collect the health status for a child 
                           controller produced by the driver.

  @param  HealthStatus     A pointer to the health status that is returned by this 
                           function.  This is an optional parameter that may be NULL.  
                           This parameter is ignored of ControllerHandle is NULL.  
                           The health status for the controller specified by 
                           ControllerHandle and ChildHandle is returned. 

  @param  MessageList      A pointer to an array of warning or error messages associated 
                           with the controller specified by ControllerHandle and 
                           ChildHandle.  This is an optional parameter that may be NULL.  
                           MessageList is allocated by this function with the EFI Boot 
                           Service AllocatePool(), and it is the caller's responsibility 
                           to free MessageList with the EFI Boot Service FreePool().  
                           Each message is specified by tuple of an EFI_HII_HANDLE and 
                           an EFI_STRING_ID.  The array of messages is terminated by tuple 
                           containing a EFI_HII_HANDLE with a value of NULL.  The 
                           EFI_HII_STRING_PROTOCOL.GetString() function can be used to 
                           retrieve the warning or error message as a Null-terminated 
                           Unicode string in a specific language.  Messages may be 
                           returned for any of the HealthStatus values except 
                           EfiDriverHealthStatusReconnectRequired and 
                           EfiDriverHealthStatusRebootRequired.

  @param  FormHiiHandle    A pointer to the HII handle for an HII form associated with the 
                           controller specified by ControllerHandle and ChildHandle.  
                           This is an optional parameter that may be NULL.  An HII form 
                           is specified by a combination of an EFI_HII_HANDLE and an 
                           EFI_GUID that identifies the Form Set GUID.  The 
                           EFI_FORM_BROWSER2_PROTOCOL.SendForm() function can be used 
                           to display and allow the user to make configuration changes 
                           to the HII Form.  An HII form may only be returned with a 
                           HealthStatus value of EfiDriverHealthStatusConfigurationRequired.

  @param  FormSetGuid      A pointer to the GUID for an HII form associated with the 
                           controller specified by ControllerHandle and ChildHandle.  
                           This is an optional parameter that may be NULL.  An HII form 
                           is specified by a combination of an EFI_HII_HANDLE and an 
                           EFI_GUID that identifies the Form Set GUID.  The 
                           EFI_FORM_BROWSER2_PROTOCOL.SendForm() function can be used 
                           to display and allow the user to make configuration changes 
                           to the HII Form.  An HII form may only be returned with a 
                           HealthStatus value of EfiDriverHealthStatusConfigurationRequired.

  @retval EFI_SUCCESS           ControllerHandle is NULL, and all the controllers 
                                managed by this driver specified by This have a health 
                                status of EfiDriverHealthStatusHealthy with no warning 
                                messages to be returned.  The ChildHandle, HealthStatus, 
                                MessageList, and FormList parameters are ignored.

  @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the 
                                controllers managed by this driver specified by This 
                                do not have a health status of EfiDriverHealthStatusHealthy.  
                                The ChildHandle, HealthStatus, MessageList, and 
                                FormList parameters are ignored.

  @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the 
                                controllers managed by this driver specified by This 
                                have one or more warning and/or error messages.  
                                The ChildHandle, HealthStatus, MessageList, and 
                                FormList parameters are ignored.

  @retval EFI_SUCCESS           ControllerHandle is not NULL and the health status 
                                of the controller specified by ControllerHandle and 
                                ChildHandle was returned in HealthStatus.  A list 
                                of warning and error messages may be optionally 
                                returned in MessageList, and a list of HII Forms 
                                may be optionally returned in FormList.

  @retval EFI_UNSUPPORTED	      ControllerHandle is not NULL, and the controller 
                                specified by ControllerHandle and ChildHandle is not 
                                currently being managed by the driver specified by This.

  @retval EFI_INVALID_PARAMETER	HealthStatus is NULL.

  @retval EFI_OUT_OF_RESOURCES	MessageList is not NULL, and there are not enough 
                                resource available to allocate memory for MessageList.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_DRIVER_HEALTH_GET_HEALTH_STATUS)(
  IN  EFI_DRIVER_HEALTH_PROTOCOL       *This,
  IN  EFI_HANDLE                       ControllerHandle  OPTIONAL,
  IN  EFI_HANDLE                       ChildHandle       OPTIONAL,
  OUT EFI_DRIVER_HEALTH_HEALTH_STATUS  *HealthStatus,
  OUT EFI_DRIVER_HEALTH_HII_MESSAGE    **MessageList     OPTIONAL,
  OUT EFI_HII_HANDLE                   *FormHiiHandle    OPTIONAL,
  OUT EFI_GUID                         **FormSetGuid     OPTIONAL
  );

/**
  Performs a repair operation on a controller in the platform.  This function can 
  optionally report repair progress information back to the platform. 
  
  @param  This             A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
  @param  ControllerHandle The handle of the controller to repair.
  @param  ChildHandle      The handle of the child controller to repair.  This is 
                           an optional parameter that may be NULL.  It will be NULL 
                           for device drivers.  It will also be NULL for bus 
                           drivers when an attempt is made to repair a bus controller.
                           If will not be NULL when an attempt is made to repair a 
                           child controller produced by the driver.
  @param  ProgressNotification
                           A notification function that may be used by a driver to 
                           report the progress of the repair operation.  This is 
                           an optional parameter that may be NULL.  


  @retval EFI_SUCCESS	          An attempt to repair the controller specified by 
                                ControllerHandle and ChildHandle was performed.  
                                The result of the repair operation can bet 
                                determined by calling GetHealthStatus().
  @retval EFI_UNSUPPORTED	      The driver specified by This is not currently 
                                managing the controller specified by ControllerHandle 
                                and ChildHandle.
  @retval EFI_OUT_OF_RESOURCES	There are not enough resources to perform the 
                                repair operation.

*/
typedef
EFI_STATUS
(EFIAPI *EFI_DRIVER_HEALTH_REPAIR)(
  IN  EFI_DRIVER_HEALTH_PROTOCOL                *This,
  IN  EFI_HANDLE                                ControllerHandle,
  IN  EFI_HANDLE                                ChildHandle           OPTIONAL,
  IN  EFI_DRIVER_HEALTH_REPAIR_PROGRESS_NOTIFY  ProgressNotification  OPTIONAL
  );

/**
  When installed, the Driver Health Protocol produces a collection of services 
  that allow the health status for a controller to be retrieved.  If a controller 
  is not in a usable state, status messages may be reported to the user, repair 
  operations can be invoked, and the user may be asked to make software and/or 
  hardware configuration changes. 

  @par Protocol Description:
  The Driver Health Protocol is optionally produced by a driver that follows the 
  EFI Driver Model.  If an EFI Driver needs to report health status to the platform, 
  provide warning or error messages to the user, perform length repair operations, 
  or request the user to make hardware or software configuration changes, then the 
  Driver Health Protocol must be produced.
  
  A controller that is managed by driver that follows the EFI Driver Model and 
  produces the Driver Health Protocol must report the current health of the 
  controllers that the driver is currently managing.  The controller can initially 
  be healthy, failed, require repair, or require configuration.  If a controller 
  requires configuration, and the user make configuration changes, the controller 
  may then need to be reconnected or the system may need to be rebooted for the 
  configuration changes to take affect.  Figure 2-1 below shows all the possible 
  health states of a controller and the legal transitions between the health states. 

  @param GetHealthStatus     Retrieves the health status of a controller in the 
                             platform.  This function can also optionally return 
                             warning messages, error messages, and a set of HII 
                             Forms that may be repair a controller that is not 
                             properly configured.
  @param Repair              Performs a repair operation on a controller in the 
                             platform.  This function can optionally report repair 
                             progress information back to the platform.

**/
struct _EFI_DRIVER_HEALTH_PROTOCOL {
  EFI_DRIVER_HEALTH_GET_HEALTH_STATUS  GetHealthStatus;
  EFI_DRIVER_HEALTH_REPAIR             Repair;
};

extern EFI_GUID gEfiDriverHealthProtocolGuid;

#endif