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