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