MdePkg/Include/Protocol/PlatformToDriverConfiguration.h

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