4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EFI Driver Health Protocol definitions.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync When installed, the Driver Health Protocol produces a collection of services that allow
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the health status for a controller to be retrieved. If a controller is not in a usable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync state, status messages may be reported to the user, repair operations can be invoked,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync and the user may be asked to make software and/or hardware configuration changes.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The Driver Health Protocol is optionally produced by a driver that follows the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EFI Driver Model. If an EFI Driver needs to report health status to the platform,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync provide warning or error messages to the user, perform length repair operations,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync or request the user to make hardware or software configuration changes, then the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Driver Health Protocol must be produced.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync A controller that is managed by driver that follows the EFI Driver Model and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync produces the Driver Health Protocol must report the current health of the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync controllers that the driver is currently managing. The controller can initially
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync be healthy, failed, require repair, or require configuration. If a controller
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync requires configuration, and the user make configuration changes, the controller
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync may then need to be reconnected or the system may need to be rebooted for the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync configuration changes to take affect.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This program and the accompanying materials
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync are licensed and made available under the terms and conditions of the BSD License
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync which accompanies this distribution. The full text of the license may be found at
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @par Revision Reference:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This Protocol is defined in UEFI Specification 2.3d
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 0x2a534210, 0x9280, 0x41d8, { 0xae, 0x79, 0xca, 0xda, 0x1, 0xa2, 0xb1, 0x27 } \
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef struct _EFI_DRIVER_HEALTH_PROTOCOL EFI_DRIVER_HEALTH_PROTOCOL;
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// EFI_DRIVER_HEALTH_HEALTH_STATUS
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef enum {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// EFI_DRIVER_HEALTH_HII_MESSAGE
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef struct {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Reports the progress of a repair operation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Value A value between 0 and Limit that identifies the current
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync progress of the repair operation.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Limit The maximum value of Value for the current repair operation.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync For example, a driver that wants to specify progress in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync percent would use a Limit value of 100.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS An attempt to repair the controller specified by
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ControllerHandle and ChildHandle was performed. The
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync result of the repair operation can bet determined by
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync calling GetHealthStatus().
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_UNSUPPORTED The driver specified by This is not currently managing the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync controller specified by ControllerHandle and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ChildHandle.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_OUT_OF_RESOURCES There are not enough resources to perform the repair operation.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Retrieves the health status of a controller in the platform. This function can also
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync optionally return warning messages, error messages, and a set of HII Forms that may
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync be repair a controller that is not proper configured.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] This A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] ControllerHandle The handle of the controller to retrieve the health status
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync on. This is an optional parameter that may be NULL. If
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync this parameter is NULL, then the value of ChildHandle is
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ignored, and the combined health status of all the devices
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync that the driver is managing is returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] ChildHandle The handle of the child controller to retrieve the health
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync status on. This is an optional parameter that may be NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This parameter is ignored of ControllerHandle is NULL. It
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync will be NULL for device drivers. It will also be NULL for
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync bus drivers when an attempt is made to collect the health
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync status of the bus controller. If will not be NULL when an
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync attempt is made to collect the health status for a child
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync controller produced by the driver.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] HealthStatus A pointer to the health status that is returned by this
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync function. This is an optional parameter that may be NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This parameter is ignored of ControllerHandle is NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The health status for the controller specified by
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ControllerHandle and ChildHandle is returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] MessageList A pointer to an array of warning or error messages associated
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync with the controller specified by ControllerHandle and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ChildHandle. This is an optional parameter that may be NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync MessageList is allocated by this function with the EFI Boot
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Service AllocatePool(), and it is the caller's responsibility
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync to free MessageList with the EFI Boot Service FreePool().
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Each message is specified by tuple of an EFI_HII_HANDLE and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync an EFI_STRING_ID. The array of messages is terminated by tuple
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync containing a EFI_HII_HANDLE with a value of NULL. The
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EFI_HII_STRING_PROTOCOL.GetString() function can be used to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync retrieve the warning or error message as a Null-terminated
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync string in a specific language. Messages may be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync returned for any of the HealthStatus values except
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EfiDriverHealthStatusReconnectRequired and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EfiDriverHealthStatusRebootRequired.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] FormHiiHandle A pointer to the HII handle containing the HII form used when
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync configuration is required. The HII handle is associated with
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the controller specified by ControllerHandle and ChildHandle.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If this is NULL, then no HII form is available. An HII handle
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync will only be returned with a HealthStatus value of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EfiDriverHealthStatusConfigurationRequired.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS ControllerHandle is NULL, and all the controllers
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync managed by this driver specified by This have a health
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync status of EfiDriverHealthStatusHealthy with no warning
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync messages to be returned. The ChildHandle, HealthStatus,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync MessageList, and FormList parameters are ignored.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_DEVICE_ERROR ControllerHandle is NULL, and one or more of the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync controllers managed by this driver specified by This
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync do not have a health status of EfiDriverHealthStatusHealthy.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The ChildHandle, HealthStatus, MessageList, and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync FormList parameters are ignored.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_DEVICE_ERROR ControllerHandle is NULL, and one or more of the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync controllers managed by this driver specified by This
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync have one or more warning and/or error messages.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The ChildHandle, HealthStatus, MessageList, and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync FormList parameters are ignored.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS ControllerHandle is not NULL and the health status
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of the controller specified by ControllerHandle and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ChildHandle was returned in HealthStatus. A list
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of warning and error messages may be optionally
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync returned in MessageList, and a list of HII Forms
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync may be optionally returned in FormList.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_UNSUPPORTED ControllerHandle is not NULL, and the controller
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync specified by ControllerHandle and ChildHandle is not
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync currently being managed by the driver specified by This.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER HealthStatus is NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_OUT_OF_RESOURCES MessageList is not NULL, and there are not enough
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync resource available to allocate memory for MessageList.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync OUT EFI_DRIVER_HEALTH_HII_MESSAGE **MessageList OPTIONAL,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Performs a repair operation on a controller in the platform. This function can
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync optionally report repair progress information back to the platform.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] This A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] ControllerHandle The handle of the controller to repair.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] ChildHandle The handle of the child controller to repair. This is
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync an optional parameter that may be NULL. It will be NULL
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync for device drivers. It will also be NULL for bus
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync drivers when an attempt is made to repair a bus controller.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If will not be NULL when an attempt is made to repair a
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync child controller produced by the driver.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] ProgressNotification A notification function that may be used by a driver to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync report the progress of the repair operation. This is
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync an optional parameter that may be NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS An attempt to repair the controller specified by
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ControllerHandle and ChildHandle was performed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The result of the repair operation can bet
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync determined by calling GetHealthStatus().
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_UNSUPPORTED The driver specified by This is not currently
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync managing the controller specified by ControllerHandle
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync and ChildHandle.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_OUT_OF_RESOURCES There are not enough resources to perform the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync repair operation.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync IN EFI_DRIVER_HEALTH_REPAIR_PROGRESS_NOTIFY ProgressNotification OPTIONAL
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// When installed, the Driver Health Protocol produces a collection of services
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// that allow the health status for a controller to be retrieved. If a controller
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// is not in a usable state, status messages may be reported to the user, repair
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// operations can be invoked, and the user may be asked to make software and/or
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// hardware configuration changes.