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