EdkCompatibilityPkg/Foundation/Efi/Protocol/DriverConfiguration/DriverConfiguration.h

   1 /*++
   2
   3 Copyright (c) 2004, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14     DriverConfiguration.h
  15
  16 Abstract:
  17
  18     EFI Driver Configuration Protocol
  19
  20 Revision History
  21
  22 --*/
  23
  24 #ifndef _EFI_DRIVER_CONFIGURATION_H_
  25 #define _EFI_DRIVER_CONFIGURATION_H_
  26
  27 //
  28 // Global ID for the Driver Configuration Protocol
  29 //
  30 #define EFI_DRIVER_CONFIGURATION_PROTOCOL_GUID \
  31   { \
  32     0x107a772b, 0xd5e1, 0x11d4, 0x9a, 0x46, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d \
  33   }
  34
  35 EFI_FORWARD_DECLARATION (EFI_DRIVER_CONFIGURATION_PROTOCOL);
  36
  37 typedef enum {
  38   EfiDriverConfigurationActionNone              = 0,
  39   EfiDriverConfigurationActionStopController    = 1,
  40   EfiDriverConfigurationActionRestartController = 2,
  41   EfiDriverConfigurationActionRestartPlatform   = 3,
  42   EfiDriverConfigurationActionMaximum
  43 } EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED;
  44
  45 #define EFI_DRIVER_CONFIGURATION_SAFE_DEFAULTS          0x00000000
  46 #define EFI_DRIVER_CONFIGURATION_MANUFACTURING_DEFAULTS 0x00000001
  47 #define EFI_DRIVER_CONFIGURATION_CUSTOM_DEFAULTS        0x00000002
  48 #define EFI_DRIVER_CONFIGURATION_PERORMANCE_DEFAULTS    0x00000003
  49
  50 typedef
  51 EFI_STATUS
  52 (EFIAPI *EFI_DRIVER_CONFIGURATION_SET_OPTIONS) (
  53   IN EFI_DRIVER_CONFIGURATION_PROTOCOL                        * This,
  54   IN  EFI_HANDLE                                              ControllerHandle,
  55   IN  EFI_HANDLE                                              ChildHandle  OPTIONAL,
  56   IN  CHAR8                                                   *Language,
  57   OUT EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED                * ActionRequired
  58   );
  59
  60 /*++
  61
  62   Routine Description:
  63     Allows the user to set controller specific options for a controller that a
  64     driver is currently managing.
  65
  66   Arguments:
  67     This             - A pointer to the EFI_DRIVER_CONFIGURATION_ PROTOCOL instance.
  68     ControllerHandle - The handle of the controller to set options on.
  69     ChildHandle      - The handle of the child controller to set options on.  This
  70                        is an optional parameter that may be NULL.  It will be NULL
  71                        for device drivers, and for a bus drivers that wish to set
  72                        options for the bus controller.  It will not be NULL for a
  73                        bus driver that wishes to set options for one of its child
  74                        controllers.
  75     Language         - A pointer to a three character ISO 639-2 language identifier.
  76                        This is the language of the user interface that should be
  77                        presented to the user, and it must match one of the languages
  78                        specified in SupportedLanguages.  The number of languages
  79                        supported by a driver is up to the driver writer.
  80     ActionRequired   - A pointer to the action that the calling agent is required
  81                        to perform when this function returns.  See "Related
  82                        Definitions" for a list of the actions that the calling
  83                        agent is required to perform prior to accessing
  84                        ControllerHandle again.
  85
  86   Returns:
  87     EFI_SUCCESS           - The driver specified by This successfully set the
  88                             configuration options for the controller specified
  89                             by ControllerHandle..
  90     EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.
  91     EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid EFI_HANDLE.
  92     EFI_INVALID_PARAMETER - ActionRequired is NULL.
  93     EFI_UNSUPPORTED       - The driver specified by This does not support setting
  94                             configuration options for the controller specified by
  95                             ControllerHandle and ChildHandle.
  96     EFI_UNSUPPORTED       - The driver specified by This does not support the
  97                             language specified by Language.
  98     EFI_DEVICE_ERROR      - A device error occurred while attempt to set the
  99                             configuration options for the controller specified
 100                             by ControllerHandle and ChildHandle.
 101     EFI_OUT_RESOURCES     - There are not enough resources available to set the
 102                             configuration options for the controller specified
 103                             by ControllerHandle and ChildHandle.
 104
 105 --*/
 106 typedef
 107 EFI_STATUS
 108 (EFIAPI *EFI_DRIVER_CONFIGURATION_OPTIONS_VALID) (
 109   IN EFI_DRIVER_CONFIGURATION_PROTOCOL                        * This,
 110   IN  EFI_HANDLE                                              ControllerHandle,
 111   IN  EFI_HANDLE                                              ChildHandle  OPTIONAL
 112   );
 113
 114 /*++
 115
 116   Routine Description:
 117     Tests to see if a controller's current configuration options are valid.
 118
 119   Arguments:
 120     This             - A pointer to the EFI_DRIVER_CONFIGURATION_PROTOCOL instance.
 121     ControllerHandle - The handle of the controller to test if it's current
 122                        configuration options are valid.
 123     ChildHandle      - The handle of the child controller to test if it's current
 124                        configuration options are valid.  This is an optional
 125                        parameter that may be NULL.  It will be NULL for device
 126                        drivers.  It will also be NULL for a bus drivers that wish
 127                        to test the configuration options for the bus controller.
 128                        It will not be NULL for a bus driver that wishes to test
 129                        configuration options for one of its child controllers.
 130
 131   Returns:
 132     EFI_SUCCESS           - The controller specified by ControllerHandle and
 133                             ChildHandle that is being managed by the driver
 134                             specified by This has a valid set of  configuration
 135                             options.
 136     EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.
 137     EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid EFI_HANDLE.
 138     EFI_UNSUPPORTED       - The driver specified by This is not currently
 139                             managing the controller specified by ControllerHandle
 140                             and ChildHandle.
 141     EFI_DEVICE_ERROR      - The controller specified by ControllerHandle and
 142                             ChildHandle that is being managed by the driver
 143                             specified by This has an invalid set of configuration
 144                             options.
 145
 146 --*/
 147 typedef
 148 EFI_STATUS
 149 (EFIAPI *EFI_DRIVER_CONFIGURATION_FORCE_DEFAULTS) (
 150   IN EFI_DRIVER_CONFIGURATION_PROTOCOL                        * This,
 151   IN  EFI_HANDLE                                              ControllerHandle,
 152   IN  EFI_HANDLE                                              ChildHandle  OPTIONAL,
 153   IN  UINT32                                                  DefaultType,
 154   OUT EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED                * ActionRequired
 155   );
 156
 157 /*++
 158
 159   Routine Description:
 160     Forces a driver to set the default configuration options for a controller.
 161
 162   Arguments:
 163     This             - A pointer to the EFI_DRIVER_CONFIGURATION_ PROTOCOL instance.
 164     ControllerHandle - The handle of the controller to force default configuration options on.
 165     ChildHandle      - The handle of the child controller to force default configuration options on  This is an optional parameter that may be NULL.  It will be NULL for device drivers.  It will also be NULL for a bus drivers that wish to force default configuration options for the bus controller.  It will not be NULL for a bus driver that wishes to force default configuration options for one of its child controllers.
 166     DefaultType      - The type of default configuration options to force on the controller specified by ControllerHandle and ChildHandle.  See Table 9-1 for legal values.  A DefaultType of 0x00000000 must be supported by this protocol.
 167     ActionRequired   - A pointer to the action that the calling agent is required to perform when this function returns.  See "Related Definitions" in Section 9.1for a list of the actions that the calling agent is required to perform prior to accessing ControllerHandle again.
 168
 169   Returns:
 170     EFI_SUCCESS           - The driver specified by This successfully forced the default configuration options on the controller specified by ControllerHandle and ChildHandle.
 171     EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.
 172     EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid EFI_HANDLE.
 173     EFI_INVALID_PARAMETER - ActionRequired is NULL.
 174     EFI_UNSUPPORTED       - The driver specified by This does not support forcing the default configuration options on the controller specified by ControllerHandle and ChildHandle.
 175     EFI_UNSUPPORTED       - The driver specified by This does not support the configuration type specified by DefaultType.
 176     EFI_DEVICE_ERROR      - A device error occurred while attempt to force the default configuration options on the controller specified by  ControllerHandle and ChildHandle.
 177     EFI_OUT_RESOURCES     - There are not enough resources available to force the default configuration options on the controller specified by ControllerHandle and ChildHandle.
 178
 179 --*/
 180
 181 //
 182 // Interface structure for the Driver Configuration Protocol
 183 //
 184 typedef struct _EFI_DRIVER_CONFIGURATION_PROTOCOL {
 185   EFI_DRIVER_CONFIGURATION_SET_OPTIONS    SetOptions;
 186   EFI_DRIVER_CONFIGURATION_OPTIONS_VALID  OptionsValid;
 187   EFI_DRIVER_CONFIGURATION_FORCE_DEFAULTS ForceDefaults;
 188   CHAR8                                   *SupportedLanguages;
 189 } EFI_DRIVER_CONFIGURATION_PROTOCOL;
 190
 191 /*++
 192
 193   Protocol Description:
 194     Used to set configuration options for a controller that an EFI Driver is managing.
 195
 196   Parameters:
 197     SetOptions         - Allows the use to set drivers specific configuration
 198                          options for a controller that the driver is currently
 199                          managing.
 200     OptionsValid       - Tests to see if a controller's current configuration
 201                          options are valid.
 202     ForceDefaults      - Forces a driver to set the default configuration options
 203                          for a controller.
 204     SupportedLanguages - A Null-terminated ASCII string that contains one or more
 205                          ISO 639-2 language codes.  This is the list of language
 206                          codes that this protocol supports.
 207
 208 --*/
 209 extern EFI_GUID gEfiDriverConfigurationProtocolGuid;
 210
 211 #endif