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