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