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