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

/** @file\r
  UEFI Platform to Driver Configuration Protocol is defined in UEFI specification.\r
\r
  This is a protocol that is optionally produced by the platform and optionally consumed\r
  by a UEFI Driver in its Start() function. This protocol allows the driver to receive\r
  configuration information as part of being started.\r
\r
  Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __PLATFORM_TO_DRIVER_CONFIGUARTION_H__\r
#define __PLATFORM_TO_DRIVER_CONFIGUARTION_H__\r
\r
#define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL_GUID  \\r
  { 0x642cd590, 0x8059, 0x4c0a, { 0xa9, 0x58, 0xc5, 0xec, 0x7, 0xd2, 0x3c, 0x4b } }\r
\r
\r
typedef struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL;\r
\r
\r
/**\r
  The UEFI driver must call Query early in the Start() function\r
  before any time consuming operations are performed. If\r
  ChildHandle is NULL the driver is requesting information from\r
  the platform about the ControllerHandle that is being started.\r
  Information returned from Query may lead to the drivers Start()\r
  function failing.\r
  If the UEFI driver is a bus driver and producing a ChildHandle,\r
  the driver must call Query after the child handle has been created\r
  and an EFI_DEVICE_PATH_PROTOCOL has been placed on that handle,\r
  but before any time consuming operation is performed. If information\r
  return by Query may lead the driver to decide to not create the\r
  ChildHandle. The driver must then cleanup and remove the ChildHandle\r
  from the system.\r
  The UEFI driver repeatedly calls Query, processes the information\r
  returned by the platform, and calls Response passing in the\r
  arguments returned from Query. The Instance value passed into\r
  Response must be the same value passed into the corresponding\r
  call to Query. The UEFI driver must continuously call Query and\r
  Response until EFI_NOT_FOUND is returned by Query.\r
  If the UEFI driver does not recognize the ParameterTypeGuid, it\r
  calls Response with a ConfigurationAction of\r
  EfiPlatformConfigurationActionUnsupportedGuid. The UEFI driver\r
  must then continue calling Query and Response until EFI_NOT_FOUND\r
  is returned by Query. This gives the platform an opportunity to\r
  pass additional configuration settings using a different\r
  ParameterTypeGuid that may be supported by the driver.\r
  An Instance value of zero means return the first ParameterBlock\r
  in the set of unprocessed parameter blocks. The driver should\r
  increment the Instance value by one for each successive call to Query.\r
\r
  @param This                 A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance.\r
\r
  @param ControllerHandle     The handle the platform will return\r
                              configuration information about.\r
\r
  @param ChildHandle          The handle of the child controller to\r
                              return information on. This is an optional\r
                              parameter that may be NULL. It will be\r
                              NULL for device drivers and for bus\r
                              drivers that attempt to get options for\r
                              the bus controller. It will not be NULL\r
                              for a bus driver that attempts to get\r
                              options for one of its child controllers.\r
\r
\r
  @param Instance             Pointer to the Instance value. Zero means\r
                              return the first query data. The caller should\r
                              increment this value by one each time to retrieve\r
                              successive data.\r
\r
  @param ParameterTypeGuid    An EFI_GUID that defines the contents\r
                              of ParameterBlock. UEFI drivers must\r
                              use the ParameterTypeGuid to determine\r
                              how to parse the ParameterBlock. The caller\r
                              should not attempt to free ParameterTypeGuid.\r
\r
  @param ParameterBlock       The platform returns a pointer to the\r
                              ParameterBlock structure which\r
                              contains details about the\r
                              configuration parameters specific to\r
                              the ParameterTypeGuid. This structure\r
                              is defined based on the protocol and\r
                              may be different for different\r
                              protocols. UEFI driver decodes this\r
                              structure and its contents based on\r
                              ParameterTypeGuid. ParameterBlock is\r
                              allocated by the platform and the\r
                              platform is responsible for freeing\r
                              the ParameterBlock after Result is\r
                              called.\r
\r
  @param ParameterBlockSize   The platform returns the size of\r
                              the ParameterBlock in bytes.\r
\r
\r
  @retval EFI_SUCCESS           The platform return parameter\r
                                information for ControllerHandle.\r
\r
  @retval EFI_NOT_FOUND         No more unread Instance exists.\r
\r
  @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r
\r
  @retval EFI_INVALID_PARAMETER Instance is NULL.\r
\r
  @retval EFI_DEVICE_ERROR      A device error occurred while\r
                                attempting to return parameter block\r
                                information for the controller\r
                                specified by ControllerHandle and\r
                                ChildHandle.\r
\r
  @retval EFI_OUT_RESOURCES     There are not enough resources\r
                                available to set the configuration\r
                                options for the controller specified\r
                                by ControllerHandle and ChildHandle.\r
\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY)(\r
  IN CONST  EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,\r
  IN CONST  EFI_HANDLE  ControllerHandle,\r
  IN CONST  EFI_HANDLE  ChildHandle OPTIONAL,\r
  IN CONST  UINTN       *Instance,\r
  OUT       EFI_GUID    **ParameterTypeGuid,\r
  OUT       VOID        **ParameterBlock,\r
  OUT       UINTN       *ParameterBlockSize\r
);\r
\r
typedef enum {\r
  ///\r
  ///  The controller specified by ControllerHandle is still\r
  ///  in a usable state, and its configuration has been updated\r
  ///  via parsing the ParameterBlock. If required by the\r
  ///  parameter block, and the module supports an NVRAM store,\r
  ///  the configuration information from PB was successfully\r
  ///  saved to the NVRAM. No actions are required before\r
  ///  this controller can be used again with the updated\r
  ///  configuration settings.\r
  ///\r
  EfiPlatformConfigurationActionNone              = 0,\r
\r
  ///\r
  ///  The driver has detected that the controller specified\r
  ///  by ControllerHandle is not in a usable state and\r
  ///  needs to be stopped. The calling agent can use the\r
  ///  DisconnectControservice to perform this operation, and\r
  ///  it should be performed as soon as possible.\r
  ///\r
  EfiPlatformConfigurationActionStopController    = 1,\r
\r
  ///\r
  ///  This controller specified by ControllerHandle needs to\r
  ///  be stopped and restarted before it can be used again.\r
  ///  The calling agent can use the DisconnectController()\r
  ///  and ConnectController() services to perform this\r
  ///  operation. The restart operation can be delayed until\r
  ///  all of the configuration options have been set.\r
  ///\r
  EfiPlatformConfigurationActionRestartController = 2,\r
\r
  ///\r
  ///  A configuration change has been made that requires the\r
  ///  platform to be restarted before the controller\r
  ///  specified by ControllerHandle can be used again. The\r
  ///  calling agent can use the ResetSystem() services to\r
  ///  perform this operation. The restart operation can be\r
  ///  delayed until all of the configuration options have\r
  ///  been set.\r
  ///\r
  EfiPlatformConfigurationActionRestartPlatform   = 3,\r
\r
  ///\r
  ///  The controller specified by ControllerHandle is still\r
  ///  in a usable state; its configuration has been updated\r
  ///  via parsing the ParameterBlock. The driver tried to\r
  ///  update the driver's private NVRAM store with\r
  ///  information from ParameterBlock and failed. No actions\r
  ///  are required before this controller can be used again\r
  ///  with the updated configuration settings, but these\r
  ///  configuration settings are not guaranteed to persist\r
  ///  after ControllerHandle is stopped.\r
  ///\r
  EfiPlatformConfigurationActionNvramFailed       = 4,\r
\r
  ///\r
  /// The controller specified by ControllerHandle is still\r
  /// in a usable state; its configuration has not been updated\r
  /// via parsing the ParameterBlock. The driver did not support\r
  /// the ParameterBlock format identified by ParameterTypeGuid.\r
  /// No actions are required before this controller can be used\r
  /// again. On additional Query calls from this ControllerHandle,\r
  /// the platform should stop returning a ParameterBlock\r
  /// qualified by this same ParameterTypeGuid. If no other\r
  /// ParameterTypeGuid is supported by the platform, Query\r
  /// should return EFI_NOT_FOUND.\r
  ///\r
  EfiPlatformConfigurationActionUnsupportedGuid   = 5,\r
  EfiPlatformConfigurationActionMaximum\r
} EFI_PLATFORM_CONFIGURATION_ACTION;\r
\r
\r
/**\r
  The UEFI driver repeatedly calls Query, processes the\r
  information returned by the platform, and calls Response passing\r
  in the arguments returned from Query. The UEFI driver must\r
  continuously call Query until EFI_NOT_FOUND is returned. For\r
  every call to Query that returns EFI_SUCCESS a corrisponding\r
  call to Response is required passing in the same\r
  ContollerHandle, ChildHandle, Instance, ParameterTypeGuid,\r
  ParameterBlock, and ParameterBlockSize. The UEFI driver may\r
  update values in ParameterBlock based on rules defined by\r
  ParameterTypeGuid. The platform is responsible for freeing\r
  ParameterBlock and the UEFI driver must not try to free it.\r
\r
  @param This                A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance.\r
\r
  @param ControllerHandle    The handle the driver is returning\r
                             configuration information about.\r
\r
  @param ChildHandle         The handle of the child controller to\r
                             return information on. This is an optional\r
                             parameter that may be NULL. It will be\r
                             NULL for device drivers, and for bus\r
                             drivers that attempt to get options for\r
                             the bus controller. It will not be NULL\r
                             for a bus driver that attempts to get\r
                             options for one of its child controllers.\r
                             Instance Instance data returned from\r
                             Query().\r
\r
  @param Instance            Instance data passed to Query().\r
\r
  @param ParameterTypeGuid   ParameterTypeGuid returned from Query.\r
\r
  @param ParameterBlock      ParameterBlock returned from Query.\r
\r
  @param ParameterBlockSize  The ParameterBlock size returned from Query.\r
\r
  @param ConfigurationAction The driver tells the platform what\r
                             action is required for ParameterBlock to\r
                             take effect.\r
\r
\r
  @retval EFI_SUCCESS           The platform return parameter information\r
                                for ControllerHandle.\r
\r
  @retval EFI_NOT_FOUND         Instance was not found.\r
\r
  @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r
\r
  @retval EFI_INVALID_PARAMETER Instance is zero.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE)(\r
  IN CONST  EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,\r
  IN CONST  EFI_HANDLE  ControllerHandle,\r
  IN CONST  EFI_HANDLE  ChildHandle OPTIONAL,\r
  IN CONST  UINTN       *Instance,\r
  IN CONST  EFI_GUID    *ParameterTypeGuid,\r
  IN CONST  VOID        *ParameterBlock,\r
  IN CONST  UINTN       ParameterBlockSize ,\r
  IN CONST  EFI_PLATFORM_CONFIGURATION_ACTION ConfigurationAction\r
);\r
\r
\r
///\r
/// The EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is used by the\r
/// UEFI driver to query the platform for configuration information.\r
/// The UEFI driver calls Query() multiple times to get\r
/// configuration information from the platform. For every call to\r
/// Query() there must be a matching call to Response() so the\r
/// UEFI driver can inform the platform how it used the\r
/// information passed in from Query(). It's legal for a UEFI\r
/// driver to use Response() to inform the platform it does not\r
/// understand the data returned via Query() and thus no action was\r
/// taken.\r
///\r
struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL {\r
  EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY    Query;\r
  EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE Response;\r
};\r
\r
\r
\r
#define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_CLP_GUID   \\r
  {0x345ecc0e, 0xcb6, 0x4b75, { 0xbb, 0x57, 0x1b, 0x12, 0x9c, 0x47, 0x33,0x3e } }\r
\r
/**\r
\r
  ParameterTypeGuid provides the support for parameters\r
  communicated through the DMTF SM CLP Specification 1.0 Final\r
  Standard to be used to configure the UEFI driver. In this\r
  section the producer of the\r
  EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is platform\r
  firmware and the consumer is the UEFI driver. Note: if future\r
  versions of the DMTF SM CLP Specification require changes to the\r
  parameter block definition, a newer ParameterTypeGuid will be\r
  used.\r
**/\r
typedef struct {\r
  CHAR8   *CLPCommand;        ///<  A pointer to the null-terminated UTF-8 string that specifies the DMTF SM CLP command\r
                              ///<  line that the driver is required to parse and process when this function is called.\r
                              ///<  See the DMTF SM CLP Specification 1.0 Final Standard for details on the\r
                              ///<  format and syntax of the CLP command line string. CLPCommand buffer\r
                              ///<  is allocated by the producer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOOL.\r
  UINT32  CLPCommandLength;   ///< The length of the CLP Command in bytes.\r
  CHAR8   *CLPReturnString;   ///<  A pointer to the null-terminated UTF-8 string that indicates the CLP return status\r
                              ///<  that the driver is required to provide to the calling agent.\r
                              ///<  The calling agent may parse and/ or pass\r
                              ///<  this for processing and user feedback. The SM CLP Command Response string\r
                              ///<  buffer is filled in by the UEFI driver in the "keyword=value" format\r
                              ///<  described in the SM CLP Specification, unless otherwise requested via the SM\r
                              ///<  CLP Coutput option in the Command Line string buffer. UEFI driver's support\r
                              ///<  for this default "keyword=value" output format is required if the UEFI\r
                              ///<  driver supports this protocol, while support for other SM CLP output\r
                              ///<  formats is optional (the UEFI Driver should return an EFI_UNSUPPORTED if\r
                              ///<  the SM CLP Coutput option requested by the caller is not supported by the\r
                              ///<  UEFI Driver). CLPReturnString buffer is allocated by the consumer of the\r
                              ///<  EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL and undefined prior to the call to\r
                              ///<  Response().\r
  UINT32  CLPReturnStringLength; ///< The length of the CLP return status string in bytes.\r
  UINT8   CLPCmdStatus;       ///<  SM CLP Command Status (see DMTF SM CLP Specification 1.0 Final Standard -\r
                              ///<  Table 4) CLPErrorValue SM CLP Processing Error Value (see DMTF SM\r
                              ///<  CLP Specification 1.0 Final Standard - Table 6). This field is filled in by\r
                              ///<  the consumer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC\r
                              ///<  OL and undefined prior to the call to Response().\r
  UINT8   CLPErrorValue;      ///<  SM CLP Processing Error Value (see DMTF SM CLP Specification 1.0 Final Standard - Table 6).\r
                              ///<  This field is filled in by the consumer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL and undefined prior to the call to Response().\r
  UINT16  CLPMsgCode;         ///<  Bit 15: OEM Message Code Flag 0 = Message Code is an SM CLP Probable\r
                              ///<  Cause Value. (see SM CLP Specification Table 11) 1 = Message Code is OEM\r
                              ///<  Specific Bits 14-0: Message Code This field is filled in by the consumer of\r
                              ///<  the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL and undefined prior to the call to\r
                              ///<  Response().\r
\r
} EFI_CONFIGURE_CLP_PARAMETER_BLK;\r
\r
\r
\r
extern EFI_GUID gEfiPlatformToDriverConfigurationClpGuid;\r
\r
extern EFI_GUID gEfiPlatformToDriverConfigurationProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
d1f95000	1	/** @file\r
ee6c452c	2	UEFI Platform to Driver Configuration Protocol is defined in UEFI specification.\r
9095d37b LG	3	\r
	4	This is a protocol that is optionally produced by the platform and optionally consumed\r
	5	by a UEFI Driver in its Start() function. This protocol allows the driver to receive\r
ee6c452c	6	configuration information as part of being started.\r
d1f95000	7	\r
9095d37b	8	Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
9344f092	9	SPDX-License-Identifier: BSD-2-Clause-Patent\r
d1f95000	10	\r
d1f95000	11	**/\r
	12	\r
	13	#ifndef __PLATFORM_TO_DRIVER_CONFIGUARTION_H__\r
	14	#define __PLATFORM_TO_DRIVER_CONFIGUARTION_H__\r
	15	\r
	16	#define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL_GUID \\r
	17	{ 0x642cd590, 0x8059, 0x4c0a, { 0xa9, 0x58, 0xc5, 0xec, 0x7, 0xd2, 0x3c, 0x4b } }\r
	18	\r
	19	\r
	20	typedef struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL;\r
	21	\r
	22	\r
	23	/**\r
	24	The UEFI driver must call Query early in the Start() function\r
	25	before any time consuming operations are performed. If\r
	26	ChildHandle is NULL the driver is requesting information from\r
	27	the platform about the ControllerHandle that is being started.\r
	28	Information returned from Query may lead to the drivers Start()\r
764f4d53	29	function failing.\r
630b4187	30	If the UEFI driver is a bus driver and producing a ChildHandle,\r
764f4d53	31	the driver must call Query after the child handle has been created\r
	32	and an EFI_DEVICE_PATH_PROTOCOL has been placed on that handle,\r
	33	but before any time consuming operation is performed. If information\r
	34	return by Query may lead the driver to decide to not create the\r
	35	ChildHandle. The driver must then cleanup and remove the ChildHandle\r
	36	from the system.\r
	37	The UEFI driver repeatedly calls Query, processes the information\r
	38	returned by the platform, and calls Response passing in the\r
	39	arguments returned from Query. The Instance value passed into\r
	40	Response must be the same value passed into the corresponding\r
a65c44c9 RN	41	call to Query. The UEFI driver must continuously call Query and\r
	42	Response until EFI_NOT_FOUND is returned by Query.\r
	43	If the UEFI driver does not recognize the ParameterTypeGuid, it\r
	44	calls Response with a ConfigurationAction of\r
	45	EfiPlatformConfigurationActionUnsupportedGuid. The UEFI driver\r
	46	must then continue calling Query and Response until EFI_NOT_FOUND\r
	47	is returned by Query. This gives the platform an opportunity to\r
	48	pass additional configuration settings using a different\r
	49	ParameterTypeGuid that may be supported by the driver.\r
764f4d53	50	An Instance value of zero means return the first ParameterBlock\r
	51	in the set of unprocessed parameter blocks. The driver should\r
	52	increment the Instance value by one for each successive call to Query.\r
d1f95000	53	\r
4ca9b6c4	54	@param This A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance.\r
9095d37b	55	\r
4ca9b6c4 LG	56	@param ControllerHandle The handle the platform will return\r
4ca9b6c4 LG	57	configuration information about.\r
9095d37b	58	\r
4ca9b6c4 LG	59	@param ChildHandle The handle of the child controller to\r
	60	return information on. This is an optional\r
	61	parameter that may be NULL. It will be\r
630b4187	62	NULL for device drivers and for bus\r
4ca9b6c4 LG	63	drivers that attempt to get options for\r
	64	the bus controller. It will not be NULL\r
	65	for a bus driver that attempts to get\r
	66	options for one of its child controllers.\r
9095d37b LG	67	\r
9095d37b LG	68	\r
764f4d53	69	@param Instance Pointer to the Instance value. Zero means\r
	70	return the first query data. The caller should\r
	71	increment this value by one each time to retrieve\r
	72	successive data.\r
	73	\r
	74	@param ParameterTypeGuid An EFI_GUID that defines the contents\r
	75	of ParameterBlock. UEFI drivers must\r
	76	use the ParameterTypeGuid to determine\r
	77	how to parse the ParameterBlock. The caller\r
	78	should not attempt to free ParameterTypeGuid.\r
4ca9b6c4 LG	79	\r
4ca9b6c4 LG	80	@param ParameterBlock The platform returns a pointer to the\r
f754f721	81	ParameterBlock structure which\r
4ca9b6c4 LG	82	contains details about the\r
	83	configuration parameters specific to\r
	84	the ParameterTypeGuid. This structure\r
	85	is defined based on the protocol and\r
	86	may be different for different\r
	87	protocols. UEFI driver decodes this\r
	88	structure and its contents based on\r
bbeea0de	89	ParameterTypeGuid. ParameterBlock is\r
f754f721	90	allocated by the platform and the\r
4ca9b6c4 LG	91	platform is responsible for freeing\r
	92	the ParameterBlock after Result is\r
	93	called.\r
d1f95000	94	\r
	95	@param ParameterBlockSize The platform returns the size of\r
	96	the ParameterBlock in bytes.\r
	97	\r
	98	\r
4ca9b6c4 LG	99	@retval EFI_SUCCESS The platform return parameter\r
4ca9b6c4 LG	100	information for ControllerHandle.\r
d1f95000	101	\r
4ca9b6c4	102	@retval EFI_NOT_FOUND No more unread Instance exists.\r
d1f95000	103	\r
18bd7e85	104	@retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r
d1f95000	105	\r
	106	@retval EFI_INVALID_PARAMETER Instance is NULL.\r
	107	\r
4ca9b6c4 LG	108	@retval EFI_DEVICE_ERROR A device error occurred while\r
	109	attempting to return parameter block\r
	110	information for the controller\r
	111	specified by ControllerHandle and\r
	112	ChildHandle.\r
d1f95000	113	\r
4ca9b6c4 LG	114	@retval EFI_OUT_RESOURCES There are not enough resources\r
	115	available to set the configuration\r
	116	options for the controller specified\r
	117	by ControllerHandle and ChildHandle.\r
d1f95000	118	\r
	119	\r
	120	**/\r
	121	typedef\r
	122	EFI_STATUS\r
8b13229b	123	(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY)(\r
d1f95000	124	IN CONST EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,\r
	125	IN CONST EFI_HANDLE ControllerHandle,\r
	126	IN CONST EFI_HANDLE ChildHandle OPTIONAL,\r
764f4d53	127	IN CONST UINTN *Instance,\r
	128	OUT EFI_GUID **ParameterTypeGuid,\r
	129	OUT VOID **ParameterBlock,\r
	130	OUT UINTN *ParameterBlockSize\r
d1f95000	131	);\r
d1f95000	132	\r
d1f95000	133	typedef enum {\r
cce6f7aa	134	///\r
cce6f7aa	135	/// The controller specified by ControllerHandle is still\r
630b4187	136	/// in a usable state, and its configuration has been updated\r
cce6f7aa	137	/// via parsing the ParameterBlock. If required by the\r
630b4187	138	/// parameter block, and the module supports an NVRAM store,\r
cce6f7aa	139	/// the configuration information from PB was successfully\r
	140	/// saved to the NVRAM. No actions are required before\r
	141	/// this controller can be used again with the updated\r
	142	/// configuration settings.\r
	143	///\r
d1f95000	144	EfiPlatformConfigurationActionNone = 0,\r
9095d37b	145	\r
cce6f7aa	146	///\r
cce6f7aa	147	/// The driver has detected that the controller specified\r
9095d37b	148	/// by ControllerHandle is not in a usable state and\r
cce6f7aa	149	/// needs to be stopped. The calling agent can use the\r
cce6f7aa	150	/// DisconnectControservice to perform this operation, and\r
9095d37b	151	/// it should be performed as soon as possible.\r
cce6f7aa	152	///\r
d1f95000	153	EfiPlatformConfigurationActionStopController = 1,\r
9095d37b	154	\r
cce6f7aa	155	///\r
	156	/// This controller specified by ControllerHandle needs to\r
	157	/// be stopped and restarted before it can be used again.\r
	158	/// The calling agent can use the DisconnectController()\r
	159	/// and ConnectController() services to perform this\r
630b4187	160	/// operation. The restart operation can be delayed until\r
9095d37b	161	/// all of the configuration options have been set.\r
cce6f7aa	162	///\r
d1f95000	163	EfiPlatformConfigurationActionRestartController = 2,\r
9095d37b	164	\r
cce6f7aa	165	///\r
	166	/// A configuration change has been made that requires the\r
	167	/// platform to be restarted before the controller\r
	168	/// specified by ControllerHandle can be used again. The\r
	169	/// calling agent can use the ResetSystem() services to\r
	170	/// perform this operation. The restart operation can be\r
	171	/// delayed until all of the configuration options have\r
9095d37b	172	/// been set.\r
cce6f7aa	173	///\r
d1f95000	174	EfiPlatformConfigurationActionRestartPlatform = 3,\r
cce6f7aa	175	\r
	176	///\r
	177	/// The controller specified by ControllerHandle is still\r
	178	/// in a usable state; its configuration has been updated\r
	179	/// via parsing the ParameterBlock. The driver tried to\r
	180	/// update the driver's private NVRAM store with\r
	181	/// information from ParameterBlock and failed. No actions\r
	182	/// are required before this controller can be used again\r
	183	/// with the updated configuration settings, but these\r
	184	/// configuration settings are not guaranteed to persist\r
9095d37b LG	185	/// after ControllerHandle is stopped.\r
9095d37b LG	186	///\r
d1f95000	187	EfiPlatformConfigurationActionNvramFailed = 4,\r
a65c44c9 RN	188	\r
	189	///\r
	190	/// The controller specified by ControllerHandle is still\r
	191	/// in a usable state; its configuration has not been updated\r
	192	/// via parsing the ParameterBlock. The driver did not support\r
	193	/// the ParameterBlock format identified by ParameterTypeGuid.\r
	194	/// No actions are required before this controller can be used\r
	195	/// again. On additional Query calls from this ControllerHandle,\r
	196	/// the platform should stop returning a ParameterBlock\r
	197	/// qualified by this same ParameterTypeGuid. If no other\r
	198	/// ParameterTypeGuid is supported by the platform, Query\r
	199	/// should return EFI_NOT_FOUND.\r
	200	///\r
	201	EfiPlatformConfigurationActionUnsupportedGuid = 5,\r
d1f95000	202	EfiPlatformConfigurationActionMaximum\r
	203	} EFI_PLATFORM_CONFIGURATION_ACTION;\r
	204	\r
	205	\r
	206	/**\r
	207	The UEFI driver repeatedly calls Query, processes the\r
	208	information returned by the platform, and calls Response passing\r
	209	in the arguments returned from Query. The UEFI driver must\r
	210	continuously call Query until EFI_NOT_FOUND is returned. For\r
	211	every call to Query that returns EFI_SUCCESS a corrisponding\r
	212	call to Response is required passing in the same\r
	213	ContollerHandle, ChildHandle, Instance, ParameterTypeGuid,\r
	214	ParameterBlock, and ParameterBlockSize. The UEFI driver may\r
	215	update values in ParameterBlock based on rules defined by\r
	216	ParameterTypeGuid. The platform is responsible for freeing\r
630b4187	217	ParameterBlock and the UEFI driver must not try to free it.\r
d1f95000	218	\r
f754f721	219	@param This A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance.\r
d1f95000	220	\r
f754f721	221	@param ControllerHandle The handle the driver is returning\r
f754f721	222	configuration information about.\r
d1f95000	223	\r
f754f721	224	@param ChildHandle The handle of the child controller to\r
	225	return information on. This is an optional\r
	226	parameter that may be NULL. It will be\r
	227	NULL for device drivers, and for bus\r
	228	drivers that attempt to get options for\r
	229	the bus controller. It will not be NULL\r
	230	for a bus driver that attempts to get\r
	231	options for one of its child controllers.\r
	232	Instance Instance data returned from\r
	233	Query().\r
d1f95000	234	\r
f754f721	235	@param Instance Instance data passed to Query().\r
764f4d53	236	\r
f754f721	237	@param ParameterTypeGuid ParameterTypeGuid returned from Query.\r
d1f95000	238	\r
f754f721	239	@param ParameterBlock ParameterBlock returned from Query.\r
d1f95000	240	\r
f754f721	241	@param ParameterBlockSize The ParameterBlock size returned from Query.\r
d1f95000	242	\r
f754f721	243	@param ConfigurationAction The driver tells the platform what\r
	244	action is required for ParameterBlock to\r
	245	take effect.\r
9095d37b LG	246	\r
9095d37b LG	247	\r
4ca9b6c4 LG	248	@retval EFI_SUCCESS The platform return parameter information\r
4ca9b6c4 LG	249	for ControllerHandle.\r
9095d37b	250	\r
4ca9b6c4	251	@retval EFI_NOT_FOUND Instance was not found.\r
9095d37b	252	\r
18bd7e85	253	@retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r
9095d37b	254	\r
d1f95000	255	@retval EFI_INVALID_PARAMETER Instance is zero.\r
9095d37b	256	\r
d1f95000	257	**/\r
	258	typedef\r
	259	EFI_STATUS\r
8b13229b	260	(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE)(\r
d1f95000	261	IN CONST EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,\r
	262	IN CONST EFI_HANDLE ControllerHandle,\r
	263	IN CONST EFI_HANDLE ChildHandle OPTIONAL,\r
	264	IN CONST UINTN *Instance,\r
	265	IN CONST EFI_GUID *ParameterTypeGuid,\r
	266	IN CONST VOID *ParameterBlock,\r
	267	IN CONST UINTN ParameterBlockSize ,\r
	268	IN CONST EFI_PLATFORM_CONFIGURATION_ACTION ConfigurationAction\r
	269	);\r
	270	\r
	271	\r
44717a39	272	///\r
	273	/// The EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is used by the\r
	274	/// UEFI driver to query the platform for configuration information.\r
	275	/// The UEFI driver calls Query() multiple times to get\r
	276	/// configuration information from the platform. For every call to\r
	277	/// Query() there must be a matching call to Response() so the\r
	278	/// UEFI driver can inform the platform how it used the\r
	279	/// information passed in from Query(). It's legal for a UEFI\r
	280	/// driver to use Response() to inform the platform it does not\r
	281	/// understand the data returned via Query() and thus no action was\r
	282	/// taken.\r
	283	///\r
d1f95000	284	struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL {\r
	285	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY Query;\r
	286	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE Response;\r
	287	};\r
	288	\r
	289	\r
	290	\r
	291	#define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_CLP_GUID \\r
	292	{0x345ecc0e, 0xcb6, 0x4b75, { 0xbb, 0x57, 0x1b, 0x12, 0x9c, 0x47, 0x33,0x3e } }\r
	293	\r
	294	/**\r
9095d37b	295	\r
d1f95000	296	ParameterTypeGuid provides the support for parameters\r
	297	communicated through the DMTF SM CLP Specification 1.0 Final\r
	298	Standard to be used to configure the UEFI driver. In this\r
	299	section the producer of the\r
	300	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is platform\r
	301	firmware and the consumer is the UEFI driver. Note: if future\r
	302	versions of the DMTF SM CLP Specification require changes to the\r
630b4187	303	parameter block definition, a newer ParameterTypeGuid will be\r
d1f95000	304	used.\r
d1f95000	305	**/\r
d1f95000	306	typedef struct {\r
9095e76b	307	CHAR8 *CLPCommand; ///< A pointer to the null-terminated UTF-8 string that specifies the DMTF SM CLP command\r
9095d37b LG	308	///< line that the driver is required to parse and process when this function is called.\r
9095d37b LG	309	///< See the DMTF SM CLP Specification 1.0 Final Standard for details on the\r
11f2f87e	310	///< format and syntax of the CLP command line string. CLPCommand buffer\r
	311	///< is allocated by the producer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOOL.\r
	312	UINT32 CLPCommandLength; ///< The length of the CLP Command in bytes.\r
9095e76b LG	313	CHAR8 *CLPReturnString; ///< A pointer to the null-terminated UTF-8 string that indicates the CLP return status\r
	314	///< that the driver is required to provide to the calling agent.\r
	315	///< The calling agent may parse and/ or pass\r
11f2f87e	316	///< this for processing and user feedback. The SM CLP Command Response string\r
	317	///< buffer is filled in by the UEFI driver in the "keyword=value" format\r
	318	///< described in the SM CLP Specification, unless otherwise requested via the SM\r
	319	///< CLP Coutput option in the Command Line string buffer. UEFI driver's support\r
	320	///< for this default "keyword=value" output format is required if the UEFI\r
	321	///< driver supports this protocol, while support for other SM CLP output\r
	322	///< formats is optional (the UEFI Driver should return an EFI_UNSUPPORTED if\r
	323	///< the SM CLP Coutput option requested by the caller is not supported by the\r
	324	///< UEFI Driver). CLPReturnString buffer is allocated by the consumer of the\r
	325	///< EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL and undefined prior to the call to\r
9095d37b	326	///< Response().\r
11f2f87e	327	UINT32 CLPReturnStringLength; ///< The length of the CLP return status string in bytes.\r
	328	UINT8 CLPCmdStatus; ///< SM CLP Command Status (see DMTF SM CLP Specification 1.0 Final Standard -\r
	329	///< Table 4) CLPErrorValue SM CLP Processing Error Value (see DMTF SM\r
	330	///< CLP Specification 1.0 Final Standard - Table 6). This field is filled in by\r
9095d37b LG	331	///< the consumer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC\r
9095d37b LG	332	///< OL and undefined prior to the call to Response().\r
11f2f87e	333	UINT8 CLPErrorValue; ///< SM CLP Processing Error Value (see DMTF SM CLP Specification 1.0 Final Standard - Table 6).\r
9095d37b	334	///< This field is filled in by the consumer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL and undefined prior to the call to Response().\r
11f2f87e	335	UINT16 CLPMsgCode; ///< Bit 15: OEM Message Code Flag 0 = Message Code is an SM CLP Probable\r
	336	///< Cause Value. (see SM CLP Specification Table 11) 1 = Message Code is OEM\r
	337	///< Specific Bits 14-0: Message Code This field is filled in by the consumer of\r
	338	///< the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL and undefined prior to the call to\r
9095d37b	339	///< Response().\r
11f2f87e	340	\r
d1f95000	341	} EFI_CONFIGURE_CLP_PARAMETER_BLK;\r
	342	\r
	343	\r
	344	\r
	345	extern EFI_GUID gEfiPlatformToDriverConfigurationClpGuid;\r
	346	\r
	347	extern EFI_GUID gEfiPlatformToDriverConfigurationProtocolGuid;\r
	348	\r
	349	#endif\r