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