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