[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 - 2007, 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\r
                EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL\r
                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\r
                EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL\r
                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\r
                           Query.\r
\r
  @param ParameterBlock ParameterBlock returned from Query.\r
\r
  @param ParameterBlockSize The ParameterBlock size returned\r
                            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\r
                                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
  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
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
	5	Copyright (c) 2006 - 2007, Intel Corporation\r
	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
	51	@param This A pointer to the\r
	52	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL\r
	53	instance.\r
	54	\r
	55	@param ControllerHandle The handle the platform will return\r
	56	configuration information about.\r
	57	\r
	58	@param ChildHandle The handle of the child controller to\r
	59	return information on. This is an optional\r
	60	parameter that may be NULL. It will be\r
	61	NULL for device drivers, and for bus\r
	62	drivers that attempt to get options for\r
	63	the bus controller. It will not be NULL\r
	64	for a bus driver that attempts to get\r
	65	options for one of its child controllers.\r
	66	\r
	67	\r
	68	@param Instance Pointer to the Instance value. On output the\r
	69	instance associated with the parameter data\r
	70	return. On input zero means return the first\r
	71	query data or pass in a valid instance\r
	72	number returned from a previous call to\r
	73	Query.\r
	74	\r
	75	@param ParameterTypeGuid An EFI_GUID that defines the\r
	76	contents of ParameterBlock. UEFI\r
	77	drivers must use the\r
78	ParameterTypeGuid to determine how\r
79	to parser the ParameterBlock.\r
80	\r
81	@param ParameterBlock The platform returns a pointer to the\r
82	ParameterBlock structure which\r
83	contains details about the\r
84	configuration parameters specific to\r
85	the ParameterTypeGuid. This structure\r
86	is defined based on the protocol and\r
87	may be different for different\r
88	protocols. UEFI driver decodes this\r
89	structure and its contents based on\r
90	ProtocolGuid. ParameterBlock is\r
91	allocated by the platform and the\r
92	platform is responsible for freeing\r
93	the ParameterBlock after Result is\r
94	called.\r
95	\r
96	@param ParameterBlockSize The platform returns the size of\r
97	the ParameterBlock in bytes.\r
98	\r
99	\r
100	@retval EFI_SUCCESS The platform return parameter\r
101	information for ControllerHandle.\r
102	\r
103	@retval EFI_NOT_FOUND No more unread Instance exists.\r
104	\r
105	@retval EFI_INVALID_PARAMETER ControllerHandle is not a valid\r
106	EFI_HANDLE.\r
107	\r
108	@retval EFI_INVALID_PARAMETER Instance is NULL.\r
109	\r
110	@retval EFI_DEVICE_ERROR A device error occurred while\r
111	attempting to return parameter block\r
112	information for the controller\r
113	specified by ControllerHandle and\r
114	ChildHandle.\r
115	\r
116	@retval EFI_OUT_RESOURCES There are not enough resources\r
117	available to set the configuration\r
118	options for the controller specified\r
119	by ControllerHandle and ChildHandle.\r
120	\r
121	\r
122	**/\r
123	typedef\r
124	EFI_STATUS\r
125	(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY) (\r
126	IN CONST EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,\r
127	IN CONST EFI_HANDLE ControllerHandle,\r
128	IN CONST EFI_HANDLE ChildHandle OPTIONAL,\r
129	IN OUT UINTN *Instance,\r
130	IN OUT EFI_GUID **ParameterTypeGuid,\r
131	IN OUT VOID **ParameterBlock,\r
132	IN OUT UINTN *ParameterBlockSize\r
133	);\r
134	\r
135	/**\r
136	\r
137	@param EfiPlatformConfigurationActionNone\r
138	The controller specified by ControllerHandle is still\r
139	in a usable state, it's configuration has been updated\r
140	via parsing the ParameterBlock. If required by the\r
141	parameter block and the module supports an NVRAM store\r
142	the configuration information from PB was successfully\r
143	saved to the NVRAM. No actions are required before\r
144	this controller can be used again with the updated\r
145	configuration settings.\r
146	\r
147	\r
148	@param EfiPlatformConfigurationStopController \r
149	The driver has detected that the controller specified\r
150	by ControllerHandle is not in a usable state, and it\r
151	needs to be stopped. The calling agent can use the\r
152	DisconnectControservice to perform this operation, and\r
153	it should be performed as soon as possible.\r
154	\r
155	@param EfiPlatformConfigurationRestartController\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
160	operation. The restart operation can be delayed until\r
161	all of the configuratiooptions have been set.\r
162	\r
163	\r
164	@param EfiPlatformConfigurationRestartPlatform\r
165	A configuration change has been made that requires the\r
166	platform to be restarted before the controller\r
167	specified by ControllerHandle can be used again. The\r
168	calling agent can use the ResetSystem() services to\r
169	perform this operation. The restart operation can be\r
170	delayed until all of the configuration options have\r
171	been set.\r
172	\r
173	@param EfiPlatformConfigurationActionNvramFailed \r
174	The controller specified by ControllerHandle is still\r
175	in a usable state; its configuration has been updated\r
176	via parsing the ParameterBlock. The driver tried to\r
177	update the driver's private NVRAM store with\r
178	information from ParameterBlock and failed. No actions\r
179	are required before this controller can be used again\r
180	with the updated configuration settings, but these\r
181	configuration settings are not guaranteed to persist\r
182	after ControllerHandle is stopped.\r
183	\r
184	**/\r
185	typedef enum {\r
186	EfiPlatformConfigurationActionNone = 0,\r
187	EfiPlatformConfigurationActionStopController = 1,\r
188	EfiPlatformConfigurationActionRestartController = 2,\r
189	EfiPlatformConfigurationActionRestartPlatform = 3,\r
190	EfiPlatformConfigurationActionNvramFailed = 4,\r
191	EfiPlatformConfigurationActionMaximum\r
192	} EFI_PLATFORM_CONFIGURATION_ACTION;\r
193	\r
194	\r
195	/**\r
196	The UEFI driver repeatedly calls Query, processes the\r
197	information returned by the platform, and calls Response passing\r
198	in the arguments returned from Query. The UEFI driver must\r
199	continuously call Query until EFI_NOT_FOUND is returned. For\r
200	every call to Query that returns EFI_SUCCESS a corrisponding\r
201	call to Response is required passing in the same\r
202	ContollerHandle, ChildHandle, Instance, ParameterTypeGuid,\r
203	ParameterBlock, and ParameterBlockSize. The UEFI driver may\r
204	update values in ParameterBlock based on rules defined by\r
205	ParameterTypeGuid. The platform is responsible for freeing\r
206	ParameterBlock and the UEFI driver must not try to free it\r
207	\r
208	@param This A pointer to the\r
209	EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL\r
210	instance.\r
211	\r
212	@param ControllerHandle The handle the driver is returning\r
213	configuration information about.\r
214	\r
215	@param ChildHandle The handle of the child controller to\r
216	return information on. This is an optional\r
217	parameter that may be NULL. It will be\r
218	NULL for device drivers, and for bus\r
219	drivers that attempt to get options for\r
220	the bus controller. It will not be NULL\r
221	for a bus driver that attempts to get\r
222	options for one of its child controllers.\r
223	Instance Instance data returned from\r
224	Query().\r
225	\r
226	@param ParameterTypeGuid ParameterTypeGuid returned from\r
227	Query.\r
228	\r
229	@param ParameterBlock ParameterBlock returned from Query.\r
230	\r
231	@param ParameterBlockSize The ParameterBlock size returned\r
232	from Query.\r
233	\r
234	@param Configuration ActionThe driver tells the platform what\r
235	action is required for ParameterBlock to\r
236	take effect.\r
237	\r
238	\r
239	@retval EFI_SUCCESS The platform return parameter information\r
240	for ControllerHandle.\r
241	\r
242	@retval EFI_NOT_FOUND Instance was not found.\r
243	\r
244	@retval EFI_INVALID_PARAMETER ControllerHandle is not a valid\r
245	EFI_HANDLE.\r
246	\r
247	@retval EFI_INVALID_PARAMETER Instance is zero.\r
248	\r
249	**/\r
250	typedef\r
251	EFI_STATUS\r
252	(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE) (\r
253	IN CONST EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,\r
254	IN CONST EFI_HANDLE ControllerHandle,\r
255	IN CONST EFI_HANDLE ChildHandle OPTIONAL,\r
256	IN CONST UINTN *Instance,\r
257	IN CONST EFI_GUID *ParameterTypeGuid,\r
258	IN CONST VOID *ParameterBlock,\r
259	IN CONST UINTN ParameterBlockSize ,\r
260	IN CONST EFI_PLATFORM_CONFIGURATION_ACTION ConfigurationAction\r
261	);\r
262	\r
263	\r
264	/**\r
265	The EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is used by the\r
266	UEFI driver to query the platform for configuration information.\r
267	The UEFI driver calls Query() multiple times to get\r
268	configuration information from the platform. For every call to\r
269	Query() there must be a matching call to Response() so the\r
270	UEFI driver can inform the platform how it used the\r
271