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

/** @file\r
  The file provides the protocol to retrieve configuration\r
  information for a device that a UEFI driver is about to start.\r
\r
  Copyright (c) 2006 - 2008, Intel Corporation \r
  All rights reserved. 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
**/\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. If the UEFI driver is a bus driver and\r
  producing a ChildHandle the driver must call Query after the\r
  child handle has been created and an EFI_DEVICE_PATH_PROTOCOL\r
  has been placed on that handle, but before any time consuming\r
  operation is performed. If information return by Query may lead\r
  the driver to decide to not create the ChildHandle. The driver\r
  must then cleanup and remove the ChildHandle from the system.\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 Instance value passed\r
  into Response must be the same value returned from the\r
  corresponding call to Query. The UEFI driver must continuously\r
  call Query and Response until EFI_NOT_FOUND is returned by\r
  Query. The only value of Instance that has meaning to the UEFI\r
  driver is zero. An Instance value of zero means return the first\r
  ParameterBlock in the set of unprocessed parameter blocks. If a\r
  ParameterBlock has been processed via a Query and corresponding\r
  Response call it must not be returned again via a Query call.\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. On output the\r
                              instance associated with the parameter data\r
                              return. On input zero means return the first\r
                              query data or pass in a valid instance\r
                              number returned from a previous call to\r
                              Query.\r
\r
  @param ParameterTypeGuid    An EFI_GUID that defines the\r
                              contents of ParameterBlock. UEFI\r
                              drivers must use the\r
                              ParameterTypeGuid to determine how\r
                              to parser the ParameterBlock.\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
                              ProtocolGuid. 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 not a valid\r
                                EFI_HANDLE.\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 OUT    UINTN       *Instance,\r
  IN OUT    EFI_GUID    **ParameterTypeGuid,\r
  IN OUT    VOID        **ParameterBlock,\r
  IN OUT    UINTN       *ParameterBlockSize\r
);\r
\r
/**\r
\r
  @param EfiPlatformConfigurationActionNone\r
          The controller specified by ControllerHandle is still\r
          in a usable state, it's 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
\r
  @param EfiPlatformConfigurationStopController \r
          The driver has detected that the controller specified\r
          by ControllerHandle  is not in a usable state, and it\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
  @param EfiPlatformConfigurationRestartController\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 configuratiooptions have been set.\r
\r
\r
  @param EfiPlatformConfigurationRestartPlatform\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
  @param EfiPlatformConfigurationActionNvramFailed \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
**/\r
typedef enum {\r
  EfiPlatformConfigurationActionNone              = 0,\r
  EfiPlatformConfigurationActionStopController    = 1,\r
  EfiPlatformConfigurationActionRestartController = 2,\r
  EfiPlatformConfigurationActionRestartPlatform   = 3,\r
  EfiPlatformConfigurationActionNvramFailed       = 4,\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 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 Configuration      ActionThe 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 not a valid EFI_HANDLE.\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
  @par Protocol Description:\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
  @param  Query     Called by the UEFI Driver Start() function to\r
                    get configuration information from the\r
                    platform.\r
  \r
  @param  Response  Called by the UEFI Driver Start() function\r
                    to let the platform know how UEFI driver\r
                    processed the data return from Query.\r
  \r
\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, newer ParameterTypeGuid will be\r
  used.\r
\r
  @param CLPCommand       A pointer to the DMTF SM CLP command line\r
                          null-terminated string that the driver is\r
                          required to parse and process when this\r
                          EFI_SUCCESS The platform return parameter\r
                          information for ControllerHandle.\r
                          EFI_NOT_FOUND Instance was not found.\r
                          EFI_INVALID_PARAMETER ControllerHandle is\r
                          not a valid EFI_HANDLE.\r
                          EFI_INVALID_PARAMETER Instance is zero.\r
                          function is called. See the DMTF SM CLP\r
                          Specification 1.0 Final Standard for\r
                          details on the format and syntax of the\r
                          CLP command line string. CLPCommand buffer\r
                          is allocated by the producer of the\r
                          EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOOL.\r
\r
  @param CLPCommandLength The length of the CLP Command in bytes.\r
\r
  @param CLPReturnString  A pointer to the CLP return status\r
                          string that the driver is required to\r
                          provide to the calling agent. The\r
                          calling agent may parse and/ or pass\r
                          this for processing and user feedback.\r
                          The SM CLP Command Response string\r
                          buffer is filled in by the UEFI driver\r
                          in the "keyword=value" format\r
                          described in the SM CLP Specification,\r
                          unless otherwise requested via the SM\r
                          CLP Coutput option in the Command Line\r
                          string buffer. UEFI driver's support\r
                          for this default "keyword=value"\r
                          output format is required if the UEFI\r
                          driver supports this protocol, while\r
                          support for other SM CLP output\r
                          formats is optional (the UEFI Driver\r
                          should return an EFI_UNSUPPORTED if\r
                          the SM CLP Coutput option requested by\r
                          the caller is not supported by the\r
                          UEFI Driver). CLPReturnString buffer\r
                          is allocated by the consumer of the\r
                          EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC\r
                          OL and undefined prior to the call to\r
                          Response().\r
\r
  @param CLPReturnStringLength  The length of the CLP return\r
                                status string in bytes.\r
\r
  @param CLPReturnStatus  SM CLP Command Status (see DMTF SM CLP\r
                          Specification 1.0 Final Standard -\r
                          Table 4) CLPErrorValue SM CLP\r
                          Processing Error Value (see DMTF SM\r
                          CLP Specification 1.0 Final Standard -\r
                          Table 6). This field is filled in by\r
                          the consumer of the\r
                          EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC \r
                          OL and undefined prior to the call to\r
                          Response().\r
\r
  @param CLPMessageCode   Bit 15: OEM Message Code Flag 0 =\r
                          Message Code is an SM CLP Probable\r
                          Cause Value. (see SM CLP Specification\r
                          Table 11) 1 = Message Code is OEM\r
                          Specific Bits 14-0: Message Code This\r
                          field is filled in by the consumer of\r
                          the\r
                          EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC\r
                          OL and undefined prior to the call to\r
                          Response().\r
\r
**/\r
typedef struct {\r
  CHAR8   *CLPCommand;\r
  UINT32  CLPCommandLength;\r
  CHAR8   *CLPReturnString;\r
  UINT32  CLPReturnStringLength;\r
  UINT8   CLPCmdStatus;\r
  UINT8   CLPErrorValue;\r
  UINT16  CLPMsgCode;\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
	2	The file provides the protocol to retrieve configuration\r
	3	information for a device that a UEFI driver is about to start.\r
	4	\r
4ca9b6c4	5	Copyright (c) 2006 - 2008, Intel Corporation \r
d1f95000	6	All rights reserved. This program and the accompanying materials \r
	7	are licensed and made available under the terms and conditions of the BSD License \r
	8	which accompanies this distribution. The full text of the license may be found at \r
	9	http://opensource.org/licenses/bsd-license.php \r
	10	\r
	11	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	12	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	13	\r
d1f95000	14	**/\r
	15	\r
	16	#ifndef __PLATFORM_TO_DRIVER_CONFIGUARTION_H__\r
	17	#define __PLATFORM_TO_DRIVER_CONFIGUARTION_H__\r
	18	\r
	19	#define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL_GUID \\r
	20	{ 0x642cd590, 0x8059, 0x4c0a, { 0xa9, 0x58, 0xc5, 0xec, 0x7, 0xd2, 0x3c, 0x4b } }\r
	21	\r
	22	\r
	23	typedef struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL;\r
	24	\r
	25	\r
	26	/**\r
	27	The UEFI driver must call Query early in the Start() function\r
	28	before any time consuming operations are performed. If\r
	29	ChildHandle is NULL the driver is requesting information from\r
	30	the platform about the ControllerHandle that is being started.\r
	31	Information returned from Query may lead to the drivers Start()\r
	32	function failing. If the UEFI driver is a bus driver and\r
	33	producing a ChildHandle the driver must call Query after the\r
	34	child handle has been created and an EFI_DEVICE_PATH_PROTOCOL\r
	35	has been placed on that handle, but before any time consuming\r
	36	operation is performed. If information return by Query may lead\r
	37	the driver to decide to not create the ChildHandle. The driver\r
	38	must then cleanup and remove the ChildHandle from the system.\r
	39	The UEFI driver repeatedly calls Query, processes the\r
	40	information returned by the platform, and calls Response passing\r
	41	in the arguments returned from Query. The Instance value passed\r
	42	into Response must be the same value returned from the\r
	43	corresponding call to Query. The UEFI driver must continuously\r
	44	call Query and Response until EFI_NOT_FOUND is returned by\r
	45	Query. The only value of Instance that has meaning to the UEFI\r
	46	driver is zero. An Instance value of zero means return the first\r
	47	ParameterBlock in the set of unprocessed parameter blocks. If a\r
	48	ParameterBlock has been processed via a Query and corresponding\r
	49	Response call it must not be returned again via a Query call.\r
	50	\r
4ca9b6c4	51	@param This A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance.\r
d1f95000	52	\r
4ca9b6c4 LG	53	@param ControllerHandle The handle the platform will return\r
4ca9b6c4 LG	54	configuration information about.\r
d1f95000	55	\r
4ca9b6c4 LG	56	@param ChildHandle The handle of the child controller to\r
	57	return information on. This is an optional\r
	58	parameter that may be NULL. It will be\r
	59	NULL for device drivers, and for bus\r
	60	drivers that attempt to get options for\r
	61	the bus controller. It will not be NULL\r
	62	for a bus driver that attempts to get\r
	63	options for one of its child controllers.\r
d1f95000	64	\r
d1f95000	65	\r
4ca9b6c4 LG	66	@param Instance Pointer to the Instance value. On output the\r
	67	instance associated with the parameter data\r
	68	return. On input zero means return the first\r
	69	query data or pass in a valid instance\r
	70	number returned from a previous call to\r
	71	Query.\r
	72	\r
	73	@param ParameterTypeGuid An EFI_GUID that defines the\r
	74	contents of ParameterBlock. UEFI\r
	75	drivers must use the\r
	76	ParameterTypeGuid to determine how\r
	77	to parser the ParameterBlock.\r
	78	\r
	79	@param ParameterBlock The platform returns a pointer to the\r
	80	ParameterBlock structure which\r
	81	contains details about the\r
	82	configuration parameters specific to\r
	83	the ParameterTypeGuid. This structure\r
	84	is defined based on the protocol and\r
	85	may be different for different\r
	86	protocols. UEFI driver decodes this\r
	87	structure and its contents based on\r
	88	ProtocolGuid. ParameterBlock is\r
	89	allocated by the platform and the\r
	90	platform is responsible for freeing\r
	91	the ParameterBlock after Result is\r
	92	called.\r
d1f95000	93	\r
	94	@param ParameterBlockSize The platform returns the size of\r
	95	the ParameterBlock in bytes.\r
	96	\r
	97	\r
4ca9b6c4 LG	98	@retval EFI_SUCCESS The platform return parameter\r
4ca9b6c4 LG	99	information for ControllerHandle.\r
d1f95000	100	\r
4ca9b6c4	101	@retval EFI_NOT_FOUND No more unread Instance exists.\r
d1f95000	102	\r
	103	@retval EFI_INVALID_PARAMETER ControllerHandle is not a valid\r
	104	EFI_HANDLE.\r
	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
	127	IN OUT UINTN *Instance,\r
	128	IN OUT EFI_GUID **ParameterTypeGuid,\r
	129	IN OUT VOID **ParameterBlock,\r
	130	IN OUT UINTN *ParameterBlockSize\r
	131	);\r
	132	\r
	133	/**\r
	134	\r
	135	@param EfiPlatformConfigurationActionNone\r
	136	The controller specified by ControllerHandle is still\r
	137	in a usable state, it's configuration has been updated\r
	138	via parsing the ParameterBlock. If required by the\r
	139	parameter block and the module supports an NVRAM store\r
	140	the configuration information from PB was successfully\r
	141	saved to the NVRAM. No actions are required before\r
	142	this controller can be used again with the updated\r
	143	configuration settings.\r
	144	\r
	145	\r
	146	@param EfiPlatformConfigurationStopController \r
	147	The driver has detected that the controller specified\r
	148	by ControllerHandle is not in a usable state, and it\r
	149	needs to be stopped. The calling agent can use the\r
	150	DisconnectControservice to perform this operation, and\r
	151	it should be performed as soon as possible.\r
	152	\r
	153	@param EfiPlatformConfigurationRestartController\r
	154	This controller specified by ControllerHandle needs to\r
	155	be stopped and restarted before it can be used again.\r
	156	The calling agent can use the DisconnectController()\r
	157	and ConnectController() services to perform this\r
	158	operation. The restart operation can be delayed until\r
	159	all of the configuratiooptions have been set.\r
	160	\r
	161	\r
	162	@param EfiPlatformConfigurationRestartPlatform\r
	163	A configuration change has been made that requires the\r
	164	platform to be restarted before the controller\r
	165	specified by ControllerHandle can be used again. The\r
	166	calling agent can use the ResetSystem() services to\r
	167	perform this operation. The restart operation can be\r
	168	delayed until all of the configuration options have\r
	169	been set.\r
	170	\r
	171	@param EfiPlatformConfigurationActionNvramFailed \r
	172	The controller specified by ControllerHandle is still\r
	173	in a usable state; its configuration has been updated\r
	174	via parsing the ParameterBlock. The driver tried to\r
	175	update the driver's private NVRAM store with\r
	176	information from ParameterBlock and failed. No actions\r
	177	are required before this controller can be used again\r
	178	with the updated configuration settings, but these\r
	179	configuration settings are not guaranteed to persist\r
	180	after ControllerHandle is stopped.\r
	181	\r
	182	**/\r
	183	typedef enum {\r
	184	EfiPlatformConfigurationActionNone = 0,\r
	185	EfiPlatformConfigurationActionStopController = 1,\r
	186	EfiPlatformConfigurationActionRestartController = 2,\r
	187	EfiPlatformConfigurationActionRestartPlatform = 3,\r
188	EfiPlatformConfigurationActionNvramFailed = 4,\r
189	EfiPlatformConfigurationActionMaximum\r
190	} EFI_PLATFORM_CONFIGURATION_ACTION;\r
191	\r
192	\r
193	/**\r
194	The UEFI driver repeatedly calls Query, processes the\r
195	information returned by the platform, and calls Response passing\r
196	in the arguments returned from Query. The UEFI driver must\r
197	continuously call Query until EFI_NOT_FOUND is returned. For\r
198	every call to Query that returns EFI_SUCCESS a corrisponding\r
199	call to Response is required passing in the same\r
200	ContollerHandle, ChildHandle, Instance, ParameterTypeGuid,\r
201	ParameterBlock, and ParameterBlockSize. The UEFI driver may\r
202	update values in ParameterBlock based on rules defined by\r
203	ParameterTypeGuid. The platform is responsible for freeing\r
204	ParameterBlock and the UEFI driver must not try to free it\r
205	\r
4ca9b6c4	206	@param This A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance.\r
d1f95000	207	\r
4ca9b6c4 LG	208	@param ControllerHandle The handle the driver is returning\r
4ca9b6c4 LG	209	configuration information about.\r
d1f95000	210	\r
4ca9b6c4 LG	211	@param ChildHandle The handle of the child controller to\r
	212	return information on. This is an optional\r
	213	parameter that may be NULL. It will be\r
	214	NULL for device drivers, and for bus\r
	215	drivers that attempt to get options for\r
	216	the bus controller. It will not be NULL\r
	217	for a bus driver that attempts to get\r
	218	options for one of its child controllers.\r
	219	Instance Instance data returned from\r
	220	Query().\r
d1f95000	221	\r
4ca9b6c4	222	@param ParameterTypeGuid ParameterTypeGuid returned from Query.\r
d1f95000	223	\r
4ca9b6c4	224	@param ParameterBlock ParameterBlock returned from Query.\r
d1f95000	225	\r
4ca9b6c4	226	@param ParameterBlockSize The ParameterBlock size returned from Query.\r
d1f95000	227	\r
4ca9b6c4 LG	228	@param Configuration ActionThe driver tells the platform what\r
	229	action is required for ParameterBlock to\r
	230	take effect.\r
d1f95000	231	\r
d1f95000	232	\r
4ca9b6c4 LG	233	@retval EFI_SUCCESS The platform return parameter information\r
4ca9b6c4 LG	234	for ControllerHandle.\r
d1f95000	235	\r
4ca9b6c4	236	@retval EFI_NOT_FOUND Instance was not found.\r
d1f95000	237	\r
4ca9b6c4 LG	238	@retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
4ca9b6c4 LG	239	\r
d1f95000	240	@retval EFI_INVALID_PARAMETER Instance is zero.\r
	241	\r
	242	**/\r
	243	typedef\r
	244	EFI_STATUS\r
8b13229b	245	(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE)(\r
d1f95000	246	IN CONST EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,\r
	247	IN CONST EFI_HANDLE ControllerHandle,\r
	248	IN CONST EFI_HANDLE ChildHandle OPTIONAL,\r
	249	IN CONST UINTN *Instance,\r
	250	IN CONST EFI_GUID *ParameterTypeGuid,\r
	251	IN CONST VOID *ParameterBlock,\r
	252	IN CONST UINTN ParameterBlockSize ,\r
	253	IN CONST EFI_PLATFORM_CONFIGURATION_ACTION ConfigurationAction\r
	254	);\r
	255	\r
	256	\r
	257	/**\r
4ca9b6c4	258	@par Protocol Description:\r
d1f95000	259	The EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is used by the\r
	260	UEFI driver to query the platform for configuration information.\r
	261	The UEFI driver calls Query() multiple times to get\r
	262	configuration information from the platform. For every call to\r
	263	Query() there must be a matching call to Response() so the\r
	264	UEFI driver can inform the platform how it used the\r
ac644614	265	information passed in from Query(). It's legal for a UEFI\r
d1f95000	266	driver to use Response() to inform the platform it does not\r
	267	understand the data returned via Query() and thus no action was\r
	268	taken.\r
	269	\r
4ca9b6c4 LG	270	@param Query Called by the UEFI Driver Start() function to\r
	271	get configuration information from the\r
	272	platform.\r
d1f95000	273	\r
	274	@param Response Called by the UEFI Driver Start() function\r
	275	to let the platform know how UEFI driver\r
	276	processed the data return from Query.\r
	277	\r
	278	\r
	279	**/\r
	280	struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL {\r
	281	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY Query;\r
	282	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE Response;\r
	283	};\r
	284	\r
	285	\r
	286	\r
	287	#define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_CLP_GUID \\r
	288	{0x345ecc0e, 0xcb6, 0x4b75, { 0xbb, 0x57, 0x1b, 0x12, 0x9c, 0x47, 0x33,0x3e } }\r
	289	\r
	290	/**\r
	291	\r
	292	ParameterTypeGuid provides the support for parameters\r
	293	communicated through the DMTF SM CLP Specification 1.0 Final\r
	294	Standard to be used to configure the UEFI driver. In this\r
	295	section the producer of the\r
	296	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is platform\r
	297	firmware and the consumer is the UEFI driver. Note: if future\r
	298	versions of the DMTF SM CLP Specification require changes to the\r
	299	parameter block definition, newer ParameterTypeGuid will be\r
	300	used.\r
	301	\r
4ca9b6c4 LG	302	@param CLPCommand A pointer to the DMTF SM CLP command line\r
	303	null-terminated string that the driver is\r
	304	required to parse and process when this\r
	305	EFI_SUCCESS The platform return parameter\r
	306	information for ControllerHandle.\r
	307	EFI_NOT_FOUND Instance was not found.\r
	308	EFI_INVALID_PARAMETER ControllerHandle is\r
	309	not a valid EFI_HANDLE.\r
	310	EFI_INVALID_PARAMETER Instance is zero.\r
	311	function is called. See the DMTF SM CLP\r
	312	Specification 1.0 Final Standard for\r
	313	details on the format and syntax of the\r
	314	CLP command line string. CLPCommand buffer\r
	315	is allocated by the producer of the\r
	316	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOOL.\r
	317	\r
	318	@param CLPCommandLength The length of the CLP Command in bytes.\r
d1f95000	319	\r
	320	@param CLPReturnString A pointer to the CLP return status\r
	321	string that the driver is required to\r
	322	provide to the calling agent. The\r
	323	calling agent may parse and/ or pass\r
	324	this for processing and user feedback.\r
	325	The SM CLP Command Response string\r
	326	buffer is filled in by the UEFI driver\r
	327	in the "keyword=value" format\r
	328	described in the SM CLP Specification,\r
	329	unless otherwise requested via the SM\r
	330	CLP Coutput option in the Command Line\r
	331	string buffer. UEFI driver's support\r
	332	for this default "keyword=value"\r
	333	output format is required if the UEFI\r
	334	driver supports this protocol, while\r
	335	support for other SM CLP output\r
	336	formats is optional (the UEFI Driver\r
	337	should return an EFI_UNSUPPORTED if\r
	338	the SM CLP Coutput option requested by\r
	339	the caller is not supported by the\r
	340	UEFI Driver). CLPReturnString buffer\r
	341	is allocated by the consumer of the\r
	342	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC\r
	343	OL and undefined prior to the call to\r
	344	Response().\r
	345	\r
	346	@param CLPReturnStringLength The length of the CLP return\r
	347	status string in bytes.\r
	348	\r
	349	@param CLPReturnStatus SM CLP Command Status (see DMTF SM CLP\r
	350	Specification 1.0 Final Standard -\r
	351	Table 4) CLPErrorValue SM CLP\r
	352	Processing Error Value (see DMTF SM\r
	353	CLP Specification 1.0 Final Standard -\r
	354	Table 6). This field is filled in by\r
	355	the consumer of the\r
	356	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC \r
	357	OL and undefined prior to the call to\r
	358	Response().\r
	359	\r
	360	@param CLPMessageCode Bit 15: OEM Message Code Flag 0 =\r
	361	Message Code is an SM CLP Probable\r
	362	Cause Value. (see SM CLP Specification\r
	363	Table 11) 1 = Message Code is OEM\r
	364	Specific Bits 14-0: Message Code This\r
	365	field is filled in by the consumer of\r
	366	the\r
	367	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC\r
	368	OL and undefined prior to the call to\r
	369	Response().\r
	370	\r
	371	**/\r
	372	typedef struct {\r
	373	CHAR8 *CLPCommand;\r
	374	UINT32 CLPCommandLength;\r
	375	CHAR8 *CLPReturnString;\r
	376	UINT32 CLPReturnStringLength;\r
	377	UINT8 CLPCmdStatus;\r
	378	UINT8 CLPErrorValue;\r
	379	UINT16 CLPMsgCode;\r
	380	} EFI_CONFIGURE_CLP_PARAMETER_BLK;\r
	381	\r
	382	\r
383	\r
384	extern EFI_GUID gEfiPlatformToDriverConfigurationClpGuid;\r
385	\r
386	extern EFI_GUID gEfiPlatformToDriverConfigurationProtocolGuid;\r
387	\r
388	#endif\r