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 - 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
  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
  52                 EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL
  53                 instance.
  54
  55   @param ControllerHandle   The handle the platform will return
  56                             configuration information about.
  57
  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.
  66
  67
  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
  73                     Query.
  74
  75   @param ParameterTypeGuid  An EFI_GUID that defines the
  76                             contents of ParameterBlock. UEFI
  77                             drivers must use the
  78                             ParameterTypeGuid to determine how
  79                             to parser the ParameterBlock.
  80
  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
  94                           called.
  95
  96   @param ParameterBlockSize   The platform returns the size of
  97                               the ParameterBlock in bytes.
  98
  99
 100   @retval EFI_SUCCESS   The platform return parameter
 101                         information for ControllerHandle.
 102
 103   @retval EFI_NOT_FOUND No more unread Instance exists.
 104
 105   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid
 106                                 EFI_HANDLE.
 107
 108   @retval EFI_INVALID_PARAMETER Instance is NULL.
 109
 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
 114                             ChildHandle.
 115
 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.
 120
 121
 122 **/
 123 typedef
 124 EFI_STATUS
 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
 133 );
 134
 135 /**
 136
 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.
 146
 147
 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.
 154
 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.
 162
 163
 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
 171           been set.
 172
 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.
 183
 184 **/
 185 typedef enum {
 186   EfiPlatformConfigurationActionNone              = 0,
 187   EfiPlatformConfigurationActionStopController    = 1,
 188   EfiPlatformConfigurationActionRestartController = 2,
 189   EfiPlatformConfigurationActionRestartPlatform   = 3,
 190   EfiPlatformConfigurationActionNvramFailed       = 4,
 191   EfiPlatformConfigurationActionMaximum
 192 } EFI_PLATFORM_CONFIGURATION_ACTION;
 193
 194
 195 /**
 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
 207
 208   @param This   A pointer to the
 209                 EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL
 210                 instance.
 211
 212   @param ControllerHandle The handle the driver is returning
 213                           configuration information about.
 214
 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
 224                       Query().
 225
 226   @param ParameterTypeGuid ParameterTypeGuid returned from
 227                            Query.
 228
 229   @param ParameterBlock ParameterBlock returned from Query.
 230
 231   @param ParameterBlockSize The ParameterBlock size returned
 232                             from Query.
 233
 234   @param Configuration  ActionThe driver tells the platform what
 235                         action is required for ParameterBlock to
 236                         take effect.
 237
 238
 239   @retval EFI_SUCCESS The platform return parameter information
 240                       for ControllerHandle.
 241
 242   @retval EFI_NOT_FOUND Instance was not found.
 243
 244   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid
 245                                 EFI_HANDLE.
 246
 247   @retval EFI_INVALID_PARAMETER Instance is zero.
 248
 249 **/
 250 typedef
 251 EFI_STATUS
 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
 261 );
 262
 263
 264 /**
 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
 274   taken.
 275
 276   @param  Query   Called by the UEFI Driver Start() function to
 277                   get configuration information from the
 278                   platform.
 279
 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.
 283
 284
 285 **/
 286 struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL {
 287   EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY    Query;
 288   EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE Response;
 289 };
 290
 291
 292
 293 #define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_CLP_GUID   \
 294   {0x345ecc0e, 0xcb6, 0x4b75, { 0xbb, 0x57, 0x1b, 0x12, 0x9c, 0x47, 0x33,0x3e } }
 295
 296 /**
 297
 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
 306   used.
 307
 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.
 323
 324   @param CLPCommandLength   The length of the CLP Command in
 325                             bytes.
 326
 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
 351                           Response().
 352
 353   @param CLPReturnStringLength  The length of the CLP return
 354                                 status string in bytes.
 355
 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
 362                           the consumer of the
 363                           EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC
 364                           OL and undefined prior to the call to
 365                           Response().
 366
 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
 373                           the
 374                           EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC
 375                           OL and undefined prior to the call to
 376                           Response().
 377
 378 **/
 379 typedef struct {
 380   CHAR8   *CLPCommand;
 381   UINT32  CLPCommandLength;
 382   CHAR8   *CLPReturnString;
 383   UINT32  CLPReturnStringLength;
 384   UINT8   CLPCmdStatus;
 385   UINT8   CLPErrorValue;
 386   UINT16  CLPMsgCode;
 387 } EFI_CONFIGURE_CLP_PARAMETER_BLK;
 388
 389
 390
 391 extern EFI_GUID gEfiPlatformToDriverConfigurationClpGuid;
 392
 393 extern EFI_GUID gEfiPlatformToDriverConfigurationProtocolGuid;
 394
 395 #endif