[mirror_edk2.git] / MdePkg / Include / Protocol / DriverHealth.h

/** @file\r
  EFI Driver Health Protocol definitions.\r
\r
  When installed, the Driver Health Protocol produces a collection of services that allow\r
  the health status for a controller to be retrieved. If a controller is not in a usable\r
  state, status messages may be reported to the user, repair operations can be invoked,\r
  and the user may be asked to make software and/or hardware configuration changes.\r
  \r
  The Driver Health Protocol is optionally produced by a driver that follows the \r
  EFI Driver Model.  If an EFI Driver needs to report health status to the platform, \r
  provide warning or error messages to the user, perform length repair operations, \r
  or request the user to make hardware or software configuration changes, then the \r
  Driver Health Protocol must be produced.\r
 \r
  A controller that is managed by driver that follows the EFI Driver Model and \r
  produces the Driver Health Protocol must report the current health of the \r
  controllers that the driver is currently managing.  The controller can initially \r
  be healthy, failed, require repair, or require configuration.  If a controller \r
  requires configuration, and the user make configuration changes, the controller \r
  may then need to be reconnected or the system may need to be rebooted for the \r
  configuration changes to take affect. \r
\r
  Copyright (c) 2009 - 2013, Intel Corporation. All rights reserved.<BR>\r
  This program and the accompanying materials                          \r
  are licensed and made available under the terms and conditions of the BSD License         \r
  which accompanies this distribution.  The full text of the license may be found at        \r
  http://opensource.org/licenses/bsd-license.php                                            \r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
  @par Revision Reference:\r
  This Protocol is defined in UEFI Specification 2.3d \r
\r
**/\r
\r
#ifndef __EFI_DRIVER_HEALTH_H__\r
#define __EFI_DRIVER_HEALTH_H__\r
\r
#define EFI_DRIVER_HEALTH_PROTOCOL_GUID \\r
  { \\r
    0x2a534210, 0x9280, 0x41d8, { 0xae, 0x79, 0xca, 0xda, 0x1, 0xa2, 0xb1, 0x27 } \\r
  }\r
  \r
typedef struct _EFI_DRIVER_HEALTH_PROTOCOL  EFI_DRIVER_HEALTH_PROTOCOL;\r
\r
///\r
/// EFI_DRIVER_HEALTH_HEALTH_STATUS\r
///\r
typedef enum {\r
  EfiDriverHealthStatusHealthy,\r
  EfiDriverHealthStatusRepairRequired,\r
  EfiDriverHealthStatusConfigurationRequired,\r
  EfiDriverHealthStatusFailed,\r
  EfiDriverHealthStatusReconnectRequired,\r
  EfiDriverHealthStatusRebootRequired\r
} EFI_DRIVER_HEALTH_STATUS;\r
\r
///\r
/// EFI_DRIVER_HEALTH_HII_MESSAGE\r
///\r
typedef struct {\r
  EFI_HII_HANDLE  HiiHandle;\r
  EFI_STRING_ID   StringId;\r
  UINT64          Reserved;\r
} EFI_DRIVER_HEALTH_HII_MESSAGE;\r
\r
/**\r
  Reports the progress of a repair operation\r
\r
  @param[in]  Value             A value between 0 and Limit that identifies the current \r
                                progress of the repair operation.\r
  \r
  @param[in]  Limit             The maximum value of Value for the current repair operation.\r
                                For example, a driver that wants to specify progress in \r
                                percent would use a Limit value of 100.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_DRIVER_HEALTH_REPAIR_NOTIFY)(\r
  IN UINTN  Value,\r
  IN UINTN  Limit\r
  );\r
\r
/**\r
  Retrieves the health status of a controller in the platform.  This function can also \r
  optionally return warning messages, error messages, and a set of HII Forms that may \r
  be repair a controller that is not proper configured. \r
  \r
  @param[in] This             A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.\r
\r
  @param[in] ControllerHandle The handle of the controller to retrieve the health status \r
                              on.  This is an optional parameter that may be NULL.  If \r
                              this parameter is NULL, then the value of ChildHandle is \r
                              ignored, and the combined health status of all the devices \r
                              that the driver is managing is returned.\r
\r
  @param[in] ChildHandle      The handle of the child controller to retrieve the health \r
                              status on.  This is an optional parameter that may be NULL.  \r
                              This parameter is ignored of ControllerHandle is NULL.  It \r
                              will be NULL for device drivers.  It will also be NULL for \r
                              bus drivers when an attempt is made to collect the health \r
                              status of the bus controller.  If will not be NULL when an \r
                              attempt is made to collect the health status for a child \r
                              controller produced by the driver.\r
\r
  @param[out] HealthStatus    A pointer to the health status that is returned by this \r
                              function.  This is an optional parameter that may be NULL.  \r
                              This parameter is ignored of ControllerHandle is NULL.  \r
                              The health status for the controller specified by \r
                              ControllerHandle and ChildHandle is returned. \r
\r
  @param[out] MessageList     A pointer to an array of warning or error messages associated \r
                              with the controller specified by ControllerHandle and \r
                              ChildHandle.  This is an optional parameter that may be NULL.  \r
                              MessageList is allocated by this function with the EFI Boot \r
                              Service AllocatePool(), and it is the caller's responsibility \r
                              to free MessageList with the EFI Boot Service FreePool().  \r
                              Each message is specified by tuple of an EFI_HII_HANDLE and \r
                              an EFI_STRING_ID.  The array of messages is terminated by tuple \r
                              containing a EFI_HII_HANDLE with a value of NULL.  The \r
                              EFI_HII_STRING_PROTOCOL.GetString() function can be used to \r
                              retrieve the warning or error message as a Null-terminated \r
                              string in a specific language.  Messages may be \r
                              returned for any of the HealthStatus values except \r
                              EfiDriverHealthStatusReconnectRequired and \r
                              EfiDriverHealthStatusRebootRequired.\r
\r
  @param[out] FormHiiHandle   A pointer to the HII handle containing the HII form used when \r
                              configuration is required. The HII handle is associated with \r
                              the controller specified by ControllerHandle and ChildHandle.\r
                              If this is NULL, then no HII form is available. An HII handle\r
                              will only be returned with a HealthStatus value of \r
                              EfiDriverHealthStatusConfigurationRequired.\r
\r
  @retval EFI_SUCCESS           ControllerHandle is NULL, and all the controllers \r
                                managed by this driver specified by This have a health \r
                                status of EfiDriverHealthStatusHealthy with no warning \r
                                messages to be returned.  The ChildHandle, HealthStatus, \r
                                MessageList, and FormList parameters are ignored.\r
\r
  @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the \r
                                controllers managed by this driver specified by This \r
                                do not have a health status of EfiDriverHealthStatusHealthy.  \r
                                The ChildHandle, HealthStatus, MessageList, and \r
                                FormList parameters are ignored.\r
\r
  @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the \r
                                controllers managed by this driver specified by This \r
                                have one or more warning and/or error messages.  \r
                                The ChildHandle, HealthStatus, MessageList, and \r
                                FormList parameters are ignored.\r
\r
  @retval EFI_SUCCESS           ControllerHandle is not NULL and the health status \r
                                of the controller specified by ControllerHandle and \r
                                ChildHandle was returned in HealthStatus.  A list \r
                                of warning and error messages may be optionally \r
                                returned in MessageList, and a list of HII Forms \r
                                may be optionally returned in FormList.\r
\r
  @retval EFI_UNSUPPORTED       ControllerHandle is not NULL, and the controller \r
                                specified by ControllerHandle and ChildHandle is not \r
                                currently being managed by the driver specified by This.\r
\r
  @retval EFI_INVALID_PARAMETER HealthStatus is NULL.\r
\r
  @retval EFI_OUT_OF_RESOURCES  MessageList is not NULL, and there are not enough \r
                                resource available to allocate memory for MessageList.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_DRIVER_HEALTH_GET_HEALTH_STATUS)(\r
  IN  EFI_DRIVER_HEALTH_PROTOCOL       *This,\r
  IN  EFI_HANDLE                       ControllerHandle OPTIONAL,\r
  IN  EFI_HANDLE                       ChildHandle      OPTIONAL,\r
  OUT EFI_DRIVER_HEALTH_STATUS         *HealthStatus,\r
  OUT EFI_DRIVER_HEALTH_HII_MESSAGE    **MessageList    OPTIONAL,\r
  OUT EFI_HII_HANDLE                   *FormHiiHandle   OPTIONAL\r
  );\r
\r
/**\r
  Performs a repair operation on a controller in the platform.  This function can \r
  optionally report repair progress information back to the platform. \r
  \r
  @param[in] This              A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.\r
  @param[in] ControllerHandle  The handle of the controller to repair.\r
  @param[in] ChildHandle       The handle of the child controller to repair.  This is \r
                               an optional parameter that may be NULL.  It will be NULL \r
                               for device drivers.  It will also be NULL for bus \r
                               drivers when an attempt is made to repair a bus controller.\r
                               If will not be NULL when an attempt is made to repair a \r
                               child controller produced by the driver.\r
  @param[in] RepairNotify      A notification function that may be used by a driver to \r
                               report the progress of the repair operation.  This is \r
                               an optional parameter that may be NULL.  \r
\r
\r
  @retval EFI_SUCCESS           An attempt to repair the controller specified by \r
                                ControllerHandle and ChildHandle was performed.  \r
                                The result of the repair operation can bet \r
                                determined by calling GetHealthStatus().\r
  @retval EFI_UNSUPPORTED       The driver specified by This is not currently \r
                                managing the controller specified by ControllerHandle \r
                                and ChildHandle.\r
  @retval EFI_OUT_OF_RESOURCES  There are not enough resources to perform the \r
                                repair operation.\r
\r
*/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_DRIVER_HEALTH_REPAIR)(\r
  IN  EFI_DRIVER_HEALTH_PROTOCOL                *This,\r
  IN  EFI_HANDLE                                ControllerHandle,\r
  IN  EFI_HANDLE                                ChildHandle       OPTIONAL,\r
  IN  EFI_DRIVER_HEALTH_REPAIR_NOTIFY           RepairNotify      OPTIONAL\r
  );\r
\r
///\r
/// When installed, the Driver Health Protocol produces a collection of services\r
/// that allow the health status for a controller to be retrieved.  If a controller \r
/// is not in a usable state, status messages may be reported to the user, repair \r
/// operations can be invoked, and the user may be asked to make software and/or \r
/// hardware configuration changes. \r
///\r
struct _EFI_DRIVER_HEALTH_PROTOCOL {\r
  EFI_DRIVER_HEALTH_GET_HEALTH_STATUS  GetHealthStatus;\r
  EFI_DRIVER_HEALTH_REPAIR             Repair;\r
};\r
\r
extern EFI_GUID gEfiDriverHealthProtocolGuid;\r
\r
#endif\r
\r
\r
\r
\r
Commit	Line	Data
91750954	1	/** @file\r
	2	EFI Driver Health Protocol definitions.\r
	3	\r
	4	When installed, the Driver Health Protocol produces a collection of services that allow\r
	5	the health status for a controller to be retrieved. If a controller is not in a usable\r
	6	state, status messages may be reported to the user, repair operations can be invoked,\r
	7	and the user may be asked to make software and/or hardware configuration changes.\r
	8	\r
	9	The Driver Health Protocol is optionally produced by a driver that follows the \r
	10	EFI Driver Model. If an EFI Driver needs to report health status to the platform, \r
	11	provide warning or error messages to the user, perform length repair operations, \r
	12	or request the user to make hardware or software configuration changes, then the \r
	13	Driver Health Protocol must be produced.\r
	14	\r
	15	A controller that is managed by driver that follows the EFI Driver Model and \r
	16	produces the Driver Health Protocol must report the current health of the \r
	17	controllers that the driver is currently managing. The controller can initially \r
	18	be healthy, failed, require repair, or require configuration. If a controller \r
	19	requires configuration, and the user make configuration changes, the controller \r
	20	may then need to be reconnected or the system may need to be rebooted for the \r
	21	configuration changes to take affect. \r
	22	\r
59ec2b00	23	Copyright (c) 2009 - 2013, Intel Corporation. All rights reserved.<BR>\r
9df063a0	24	This program and the accompanying materials \r
91750954	25	are licensed and made available under the terms and conditions of the BSD License \r
	26	which accompanies this distribution. The full text of the license may be found at \r
	27	http://opensource.org/licenses/bsd-license.php \r
	28	\r
	29	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	30	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	31	\r
	32	@par Revision Reference:\r
9095e76b	33	This Protocol is defined in UEFI Specification 2.3d \r
91750954	34	\r
	35	**/\r
	36	\r
	37	#ifndef __EFI_DRIVER_HEALTH_H__\r
	38	#define __EFI_DRIVER_HEALTH_H__\r
	39	\r
	40	#define EFI_DRIVER_HEALTH_PROTOCOL_GUID \\r
	41	{ \\r
	42	0x2a534210, 0x9280, 0x41d8, { 0xae, 0x79, 0xca, 0xda, 0x1, 0xa2, 0xb1, 0x27 } \\r
	43	}\r
	44	\r
	45	typedef struct _EFI_DRIVER_HEALTH_PROTOCOL EFI_DRIVER_HEALTH_PROTOCOL;\r
	46	\r
	47	///\r
	48	/// EFI_DRIVER_HEALTH_HEALTH_STATUS\r
	49	///\r
	50	typedef enum {\r
	51	EfiDriverHealthStatusHealthy,\r
	52	EfiDriverHealthStatusRepairRequired,\r
	53	EfiDriverHealthStatusConfigurationRequired,\r
	54	EfiDriverHealthStatusFailed,\r
	55	EfiDriverHealthStatusReconnectRequired,\r
	56	EfiDriverHealthStatusRebootRequired\r
	57	} EFI_DRIVER_HEALTH_STATUS;\r
	58	\r
	59	///\r
	60	/// EFI_DRIVER_HEALTH_HII_MESSAGE\r
	61	///\r
	62	typedef struct {\r
	63	EFI_HII_HANDLE HiiHandle;\r
	64	EFI_STRING_ID StringId;\r
	65	UINT64 Reserved;\r
	66	} EFI_DRIVER_HEALTH_HII_MESSAGE;\r
	67	\r
	68	/**\r
	69	Reports the progress of a repair operation\r
	70	\r
5e33ee94	71	@param[in] Value A value between 0 and Limit that identifies the current \r
91750954	72	progress of the repair operation.\r
91750954	73	\r
5e33ee94	74	@param[in] Limit The maximum value of Value for the current repair operation.\r
91750954	75	For example, a driver that wants to specify progress in \r
91750954	76	percent would use a Limit value of 100.\r
91750954	77	**/\r
	78	typedef\r
	79	EFI_STATUS\r
59ec2b00	80	(EFIAPI *EFI_DRIVER_HEALTH_REPAIR_NOTIFY)(\r
91750954	81	IN UINTN Value,\r
	82	IN UINTN Limit\r
	83	);\r
	84	\r
	85	/**\r
	86	Retrieves the health status of a controller in the platform. This function can also \r
	87	optionally return warning messages, error messages, and a set of HII Forms that may \r
	88	be repair a controller that is not proper configured. \r
	89	\r
5e33ee94	90	@param[in] This A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.\r
	91	\r
	92	@param[in] ControllerHandle The handle of the controller to retrieve the health status \r
	93	on. This is an optional parameter that may be NULL. If \r
	94	this parameter is NULL, then the value of ChildHandle is \r
	95	ignored, and the combined health status of all the devices \r
	96	that the driver is managing is returned.\r
	97	\r
	98	@param[in] ChildHandle The handle of the child controller to retrieve the health \r
	99	status on. This is an optional parameter that may be NULL. \r
	100	This parameter is ignored of ControllerHandle is NULL. It \r
	101	will be NULL for device drivers. It will also be NULL for \r
	102	bus drivers when an attempt is made to collect the health \r
	103	status of the bus controller. If will not be NULL when an \r
	104	attempt is made to collect the health status for a child \r
	105	controller produced by the driver.\r
	106	\r
	107	@param[out] HealthStatus A pointer to the health status that is returned by this \r
	108	function. This is an optional parameter that may be NULL. \r
	109	This parameter is ignored of ControllerHandle is NULL. \r
	110	The health status for the controller specified by \r
	111	ControllerHandle and ChildHandle is returned. \r
	112	\r
	113	@param[out] MessageList A pointer to an array of warning or error messages associated \r
	114	with the controller specified by ControllerHandle and \r
	115	ChildHandle. This is an optional parameter that may be NULL. \r
	116	MessageList is allocated by this function with the EFI Boot \r
	117	Service AllocatePool(), and it is the caller's responsibility \r
	118	to free MessageList with the EFI Boot Service FreePool(). \r
	119	Each message is specified by tuple of an EFI_HII_HANDLE and \r
	120	an EFI_STRING_ID. The array of messages is terminated by tuple \r
	121	containing a EFI_HII_HANDLE with a value of NULL. The \r
	122	EFI_HII_STRING_PROTOCOL.GetString() function can be used to \r
	123	retrieve the warning or error message as a Null-terminated \r
9095e76b	124	string in a specific language. Messages may be \r
5e33ee94	125	returned for any of the HealthStatus values except \r
	126	EfiDriverHealthStatusReconnectRequired and \r
	127	EfiDriverHealthStatusRebootRequired.\r
	128	\r
25a0aa5d	129	@param[out] FormHiiHandle A pointer to the HII handle containing the HII form used when \r
	130	configuration is required. The HII handle is associated with \r
	131	the controller specified by ControllerHandle and ChildHandle.\r
	132	If this is NULL, then no HII form is available. An HII handle\r
	133	will only be returned with a HealthStatus value of \r
	134	EfiDriverHealthStatusConfigurationRequired.\r
91750954	135	\r
	136	@retval EFI_SUCCESS ControllerHandle is NULL, and all the controllers \r
	137	managed by this driver specified by This have a health \r
	138	status of EfiDriverHealthStatusHealthy with no warning \r
	139	messages to be returned. The ChildHandle, HealthStatus, \r
	140	MessageList, and FormList parameters are ignored.\r
	141	\r
	142	@retval EFI_DEVICE_ERROR ControllerHandle is NULL, and one or more of the \r
	143	controllers managed by this driver specified by This \r
	144	do not have a health status of EfiDriverHealthStatusHealthy. \r
	145	The ChildHandle, HealthStatus, MessageList, and \r
	146	FormList parameters are ignored.\r
	147	\r
	148	@retval EFI_DEVICE_ERROR ControllerHandle is NULL, and one or more of the \r
	149	controllers managed by this driver specified by This \r
	150	have one or more warning and/or error messages. \r
	151	The ChildHandle, HealthStatus, MessageList, and \r
	152	FormList parameters are ignored.\r
	153	\r
	154	@retval EFI_SUCCESS ControllerHandle is not NULL and the health status \r
	155	of the controller specified by ControllerHandle and \r
	156	ChildHandle was returned in HealthStatus. A list \r
	157	of warning and error messages may be optionally \r
	158	returned in MessageList, and a list of HII Forms \r
	159	may be optionally returned in FormList.\r
	160	\r
5e33ee94	161	@retval EFI_UNSUPPORTED ControllerHandle is not NULL, and the controller \r
91750954	162	specified by ControllerHandle and ChildHandle is not \r
	163	currently being managed by the driver specified by This.\r
	164	\r
5e33ee94	165	@retval EFI_INVALID_PARAMETER HealthStatus is NULL.\r
91750954	166	\r
5e33ee94	167	@retval EFI_OUT_OF_RESOURCES MessageList is not NULL, and there are not enough \r
91750954	168	resource available to allocate memory for MessageList.\r
	169	\r
	170	**/\r
	171	typedef\r
	172	EFI_STATUS\r
	173	(EFIAPI *EFI_DRIVER_HEALTH_GET_HEALTH_STATUS)(\r
	174	IN EFI_DRIVER_HEALTH_PROTOCOL *This,\r
	175	IN EFI_HANDLE ControllerHandle OPTIONAL,\r
	176	IN EFI_HANDLE ChildHandle OPTIONAL,\r
	177	OUT EFI_DRIVER_HEALTH_STATUS *HealthStatus,\r
	178	OUT EFI_DRIVER_HEALTH_HII_MESSAGE **MessageList OPTIONAL,\r
	179	OUT EFI_HII_HANDLE *FormHiiHandle OPTIONAL\r
	180	);\r
	181	\r
	182	/**\r
	183	Performs a repair operation on a controller in the platform. This function can \r
	184	optionally report repair progress information back to the platform. \r
	185	\r
59ec2b00 RN	186	@param[in] This A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.\r
	187	@param[in] ControllerHandle The handle of the controller to repair.\r
	188	@param[in] ChildHandle The handle of the child controller to repair. This is \r
	189	an optional parameter that may be NULL. It will be NULL \r
	190	for device drivers. It will also be NULL for bus \r
	191	drivers when an attempt is made to repair a bus controller.\r
	192	If will not be NULL when an attempt is made to repair a \r
	193	child controller produced by the driver.\r
	194	@param[in] RepairNotify A notification function that may be used by a driver to \r
	195	report the progress of the repair operation. This is \r
	196	an optional parameter that may be NULL. \r
5e33ee94	197	\r
	198	\r
	199	@retval EFI_SUCCESS An attempt to repair the controller specified by \r
91750954	200	ControllerHandle and ChildHandle was performed. \r
	201	The result of the repair operation can bet \r
	202	determined by calling GetHealthStatus().\r
5e33ee94	203	@retval EFI_UNSUPPORTED The driver specified by This is not currently \r
91750954	204	managing the controller specified by ControllerHandle \r
91750954	205	and ChildHandle.\r
5e33ee94	206	@retval EFI_OUT_OF_RESOURCES There are not enough resources to perform the \r
91750954	207	repair operation.\r
	208	\r
	209	*/\r
	210	typedef\r
	211	EFI_STATUS\r
	212	(EFIAPI *EFI_DRIVER_HEALTH_REPAIR)(\r
	213	IN EFI_DRIVER_HEALTH_PROTOCOL *This,\r
	214	IN EFI_HANDLE ControllerHandle,\r
59ec2b00 RN	215	IN EFI_HANDLE ChildHandle OPTIONAL,\r
59ec2b00 RN	216	IN EFI_DRIVER_HEALTH_REPAIR_NOTIFY RepairNotify OPTIONAL\r
91750954	217	);\r
	218	\r
	219	///\r
	220	/// When installed, the Driver Health Protocol produces a collection of services\r
	221	/// that allow the health status for a controller to be retrieved. If a controller \r
	222	/// is not in a usable state, status messages may be reported to the user, repair \r
	223	/// operations can be invoked, and the user may be asked to make software and/or \r
	224	/// hardware configuration changes. \r
	225	///\r
	226	struct _EFI_DRIVER_HEALTH_PROTOCOL {\r
	227	EFI_DRIVER_HEALTH_GET_HEALTH_STATUS GetHealthStatus;\r
	228	EFI_DRIVER_HEALTH_REPAIR Repair;\r
	229	};\r
	230	\r
	231	extern EFI_GUID gEfiDriverHealthProtocolGuid;\r
	232	\r
	233	#endif\r
	234	\r
	235	\r
	236	\r
	237	\r