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