MdePkg/Include/Protocol/PlatformToDriverConfiguration.h

   1 /** @file
   2   The file provides the protocol to retrieve configuration
   3   information for a device that a UEFI driver is about to start.
   4
   5   Copyright (c) 2006 - 2008, 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
  10
  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.
  13
  14 **/
  15
  16 #ifndef __PLATFORM_TO_DRIVER_CONFIGUARTION_H__
  17 #define __PLATFORM_TO_DRIVER_CONFIGUARTION_H__
  18
  19 #define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL_GUID  \
  20   { 0x642cd590, 0x8059, 0x4c0a, { 0xa9, 0x58, 0xc5, 0xec, 0x7, 0xd2, 0x3c, 0x4b } }
  21
  22
  23 typedef struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL;
  24
  25
  26 /**
  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.
  50
  51   @param This                 A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance.
  52
  53   @param ControllerHandle     The handle the platform will return
  54                               configuration information about.
  55
  56   @param ChildHandle          The handle of the child controller to
  57                               return information on. This is an optional
  58                               parameter that may be NULL. It will be
  59                               NULL for device drivers, and for bus
  60                               drivers that attempt to get options for
  61                               the bus controller. It will not be NULL
  62                               for a bus driver that attempts to get
  63                               options for one of its child controllers.
  64
  65
  66   @param Instance             Pointer to the Instance value. On output the
  67                               instance associated with the parameter data
  68                               return. On input zero means return the first
  69                               query data or pass in a valid instance
  70                               number returned from a previous call to
  71                               Query.
  72
  73   @param ParameterTypeGuid    An EFI_GUID that defines the
  74                               contents of ParameterBlock. UEFI
  75                               drivers must use the
  76                               ParameterTypeGuid to determine how
  77                               to parser the ParameterBlock.
  78
  79   @param ParameterBlock       The platform returns a pointer to the
  80                               ParameterBlock structure which
  81                               contains details about the
  82                               configuration parameters specific to
  83                               the ParameterTypeGuid. This structure
  84                               is defined based on the protocol and
  85                               may be different for different
  86                               protocols. UEFI driver decodes this
  87                               structure and its contents based on
  88                               ProtocolGuid. ParameterBlock is
  89                               allocated by the platform and the
  90                               platform is responsible for freeing
  91                               the ParameterBlock after Result is
  92                               called.
  93
  94   @param ParameterBlockSize   The platform returns the size of
  95                               the ParameterBlock in bytes.
  96
  97
  98   @retval EFI_SUCCESS           The platform return parameter
  99                                 information for ControllerHandle.
 100
 101   @retval EFI_NOT_FOUND         No more unread Instance exists.
 102
 103   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid
 104                                 EFI_HANDLE.
 105
 106   @retval EFI_INVALID_PARAMETER Instance is NULL.
 107
 108   @retval EFI_DEVICE_ERROR      A device error occurred while
 109                                 attempting to return parameter block
 110                                 information for the controller
 111                                 specified by ControllerHandle and
 112                                 ChildHandle.
 113
 114   @retval EFI_OUT_RESOURCES     There are not enough resources
 115                                 available to set the configuration
 116                                 options for the controller specified
 117                                 by ControllerHandle and ChildHandle.
 118
 119
 120 **/
 121 typedef
 122 EFI_STATUS
 123 (EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY)(
 124   IN CONST  EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,
 125   IN CONST  EFI_HANDLE  ControllerHandle,
 126   IN CONST  EFI_HANDLE  ChildHandle OPTIONAL,
 127   IN OUT    UINTN       *Instance,
 128   IN OUT    EFI_GUID    **ParameterTypeGuid,
 129   IN OUT    VOID        **ParameterBlock,
 130   IN OUT    UINTN       *ParameterBlockSize
 131 );
 132
 133 /**
 134
 135   @param EfiPlatformConfigurationActionNone
 136           The controller specified by ControllerHandle is still
 137           in a usable state, it's configuration has been updated
 138           via parsing the ParameterBlock. If required by the
 139           parameter block and the module supports an NVRAM store
 140           the configuration information from PB was successfully
 141           saved to the NVRAM. No actions are required before
 142           this controller can be used again with the updated
 143           configuration settings.
 144
 145
 146   @param EfiPlatformConfigurationStopController
 147           The driver has detected that the controller specified
 148           by ControllerHandle  is not in a usable state, and it
 149           needs to be stopped. The calling agent can use the
 150           DisconnectControservice to perform this operation, and
 151           it should be performed as soon as possible.
 152
 153   @param EfiPlatformConfigurationRestartController
 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 configuratiooptions have been set.
 160
 161
 162   @param EfiPlatformConfigurationRestartPlatform
 163           A configuration change has been made that requires the
 164           platform to be restarted before the controller
 165           specified by ControllerHandle can be used again. The
 166           calling agent can use the ResetSystem() services to
 167           perform this operation. The restart operation can be
 168           delayed until all of the configuration options have
 169           been set.
 170
 171   @param EfiPlatformConfigurationActionNvramFailed
 172           The controller specified by ControllerHandle is still
 173           in a usable state; its configuration has been updated
 174           via parsing the ParameterBlock. The driver tried to
 175           update the driver's private NVRAM store with
 176           information from ParameterBlock and failed. No actions
 177           are required before this controller can be used again
 178           with the updated configuration settings, but these
 179           configuration settings are not guaranteed to persist
 180           after ControllerHandle is stopped.
 181
 182 **/
 183 typedef enum {
 184   EfiPlatformConfigurationActionNone              = 0,
 185   EfiPlatformConfigurationActionStopController    = 1,
 186   EfiPlatformConfigurationActionRestartController = 2,
 187   EfiPlatformConfigurationActionRestartPlatform   = 3,
 188   EfiPlatformConfigurationActionNvramFailed       = 4,
 189   EfiPlatformConfigurationActionMaximum
 190 } EFI_PLATFORM_CONFIGURATION_ACTION;
 191
 192
 193 /**
 194   The UEFI driver repeatedly calls Query, processes the
 195   information returned by the platform, and calls Response passing
 196   in the arguments returned from Query. The UEFI driver must
 197   continuously call Query until EFI_NOT_FOUND is returned. For
 198   every call to Query that returns EFI_SUCCESS a corrisponding
 199   call to Response is required passing in the same
 200   ContollerHandle, ChildHandle, Instance, ParameterTypeGuid,
 201   ParameterBlock, and ParameterBlockSize. The UEFI driver may
 202   update values in ParameterBlock based on rules defined by
 203   ParameterTypeGuid. The platform is responsible for freeing
 204   ParameterBlock and the UEFI driver must not try to free it
 205
 206   @param This               A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance.
 207
 208   @param ControllerHandle   The handle the driver is returning
 209                             configuration information about.
 210
 211   @param ChildHandle        The handle of the child controller to
 212                             return information on. This is an optional
 213                             parameter that may be NULL. It will be
 214                             NULL for device drivers, and for bus
 215                             drivers that attempt to get options for
 216                             the bus controller. It will not be NULL
 217                             for a bus driver that attempts to get
 218                             options for one of its child controllers.
 219                             Instance Instance data returned from
 220                             Query().
 221
 222   @param ParameterTypeGuid  ParameterTypeGuid returned from Query.
 223
 224   @param ParameterBlock     ParameterBlock returned from Query.
 225
 226   @param ParameterBlockSize The ParameterBlock size returned from Query.
 227
 228   @param Configuration      ActionThe driver tells the platform what
 229                             action is required for ParameterBlock to
 230                             take effect.
 231
 232
 233   @retval EFI_SUCCESS           The platform return parameter information
 234                                 for ControllerHandle.
 235
 236   @retval EFI_NOT_FOUND         Instance was not found.
 237
 238   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
 239
 240   @retval EFI_INVALID_PARAMETER Instance is zero.
 241
 242 **/
 243 typedef
 244 EFI_STATUS
 245 (EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE)(
 246   IN CONST  EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,
 247   IN CONST  EFI_HANDLE  ControllerHandle,
 248   IN CONST  EFI_HANDLE  ChildHandle OPTIONAL,
 249   IN CONST  UINTN       *Instance,
 250   IN CONST  EFI_GUID    *ParameterTypeGuid,
 251   IN CONST  VOID        *ParameterBlock,
 252   IN CONST  UINTN       ParameterBlockSize ,
 253   IN CONST  EFI_PLATFORM_CONFIGURATION_ACTION ConfigurationAction
 254 );
 255
 256
 257 /**
 258   @par Protocol Description:
 259   The EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is used by the
 260   UEFI driver to query the platform for configuration information.
 261   The UEFI driver calls Query() multiple times to get
 262   configuration information from the platform. For every call to
 263   Query() there must be a matching call to Response() so the
 264   UEFI driver can inform the platform how it used the
 265   information passed in from Query(). It's legal for a UEFI
 266   driver to use Response() to inform the platform it does not
 267   understand the data returned via Query() and thus no action was
 268   taken.
 269
 270   @param  Query     Called by the UEFI Driver Start() function to
 271                     get configuration information from the
 272                     platform.
 273
 274   @param  Response  Called by the UEFI Driver Start() function
 275                     to let the platform know how UEFI driver
 276                     processed the data return from Query.
 277
 278
 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
 286
 287 #define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_CLP_GUID   \
 288   {0x345ecc0e, 0xcb6, 0x4b75, { 0xbb, 0x57, 0x1b, 0x12, 0x9c, 0x47, 0x33,0x3e } }
 289
 290 /**
 291
 292   ParameterTypeGuid provides the support for parameters
 293   communicated through the DMTF SM CLP Specification 1.0 Final
 294   Standard to be used to configure the UEFI driver. In this
 295   section the producer of the
 296   EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is platform
 297   firmware and the consumer is the UEFI driver. Note: if future
 298   versions of the DMTF SM CLP Specification require changes to the
 299   parameter block definition, newer ParameterTypeGuid will be
 300   used.
 301
 302   @param CLPCommand       A pointer to the DMTF SM CLP command line
 303                           null-terminated string that the driver is
 304                           required to parse and process when this
 305                           EFI_SUCCESS The platform return parameter
 306                           information for ControllerHandle.
 307                           EFI_NOT_FOUND Instance was not found.
 308                           EFI_INVALID_PARAMETER ControllerHandle is
 309                           not a valid EFI_HANDLE.
 310                           EFI_INVALID_PARAMETER Instance is zero.
 311                           function is called. See the DMTF SM CLP
 312                           Specification 1.0 Final Standard for
 313                           details on the format and syntax of the
 314                           CLP command line string. CLPCommand buffer
 315                           is allocated by the producer of the
 316                           EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOOL.
 317
 318   @param CLPCommandLength The length of the CLP Command in bytes.
 319
 320   @param CLPReturnString  A pointer to the CLP return status
 321                           string that the driver is required to
 322                           provide to the calling agent. The
 323                           calling agent may parse and/ or pass
 324                           this for processing and user feedback.
 325                           The SM CLP Command Response string
 326                           buffer is filled in by the UEFI driver
 327                           in the "keyword=value" format
 328                           described in the SM CLP Specification,
 329                           unless otherwise requested via the SM
 330                           CLP Coutput option in the Command Line
 331                           string buffer. UEFI driver's support
 332                           for this default "keyword=value"
 333                           output format is required if the UEFI
 334                           driver supports this protocol, while
 335                           support for other SM CLP output
 336                           formats is optional (the UEFI Driver
 337                           should return an EFI_UNSUPPORTED if
 338                           the SM CLP Coutput option requested by
 339                           the caller is not supported by the
 340                           UEFI Driver). CLPReturnString buffer
 341                           is allocated by the consumer of the
 342                           EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC
 343                           OL and undefined prior to the call to
 344                           Response().
 345
 346   @param CLPReturnStringLength  The length of the CLP return
 347                                 status string in bytes.
 348
 349   @param CLPReturnStatus  SM CLP Command Status (see DMTF SM CLP
 350                           Specification 1.0 Final Standard -
 351                           Table 4) CLPErrorValue SM CLP
 352                           Processing Error Value (see DMTF SM
 353                           CLP Specification 1.0 Final Standard -
 354                           Table 6). This field is filled in by
 355                           the consumer of the
 356                           EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC
 357                           OL and undefined prior to the call to
 358                           Response().
 359
 360   @param CLPMessageCode   Bit 15: OEM Message Code Flag 0 =
 361                           Message Code is an SM CLP Probable
 362                           Cause Value. (see SM CLP Specification
 363                           Table 11) 1 = Message Code is OEM
 364                           Specific Bits 14-0: Message Code This
 365                           field is filled in by the consumer of
 366                           the
 367                           EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC
 368                           OL and undefined prior to the call to
 369                           Response().
 370
 371 **/
 372 typedef struct {
 373   CHAR8   *CLPCommand;
 374   UINT32  CLPCommandLength;
 375   CHAR8   *CLPReturnString;
 376   UINT32  CLPReturnStringLength;
 377   UINT8   CLPCmdStatus;
 378   UINT8   CLPErrorValue;
 379   UINT16  CLPMsgCode;
 380 } EFI_CONFIGURE_CLP_PARAMETER_BLK;
 381
 382
 383
 384 extern EFI_GUID gEfiPlatformToDriverConfigurationClpGuid;
 385
 386 extern EFI_GUID gEfiPlatformToDriverConfigurationProtocolGuid;
 387
 388 #endif