MdeModulePkg/Universal/Network/Ip4ConfigDxe/Ip4Config.h

   1 /** @file
   2   Header file for IP4Config driver.
   3
   4 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at<BR>
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _EFI_IP4CONFIG_H_
  16 #define _EFI_IP4CONFIG_H_
  17
  18 #include <Uefi.h>
  19
  20 #include <Protocol/Dhcp4.h>
  21 #include <Protocol/Ip4Config.h>
  22 #include <Protocol/ManagedNetwork.h>
  23 #include <Protocol/HiiConfigAccess.h>
  24 #include <Protocol/HiiDatabase.h>
  25 #include <Protocol/HiiConfigRouting.h>
  26 #include <Protocol/ServiceBinding.h>
  27
  28 #include <Guid/MdeModuleHii.h>
  29 #include <Guid/NicIp4ConfigNvData.h>
  30
  31 #include <Library/DevicePathLib.h>
  32 #include <Library/DebugLib.h>
  33 #include <Library/UefiRuntimeServicesTableLib.h>
  34 #include <Library/UefiDriverEntryPoint.h>
  35 #include <Library/UefiBootServicesTableLib.h>
  36 #include <Library/UefiLib.h>
  37 #include <Library/NetLib.h>
  38 #include <Library/BaseMemoryLib.h>
  39 #include <Library/MemoryAllocationLib.h>
  40 #include <Library/HiiLib.h>
  41 #include <Library/PrintLib.h>
  42 #include <Library/DpcLib.h>
  43 #include <Library/UefiHiiServicesLib.h>
  44
  45
  46 //
  47 // Global variables
  48 //
  49 extern EFI_DRIVER_BINDING_PROTOCOL     gIp4ConfigDriverBinding;
  50 extern EFI_COMPONENT_NAME_PROTOCOL     gIp4ConfigComponentName;
  51 extern EFI_COMPONENT_NAME2_PROTOCOL    gIp4ConfigComponentName2;
  52
  53 extern EFI_IP4_CONFIG_PROTOCOL         mIp4ConfigProtocolTemplate;
  54
  55 #define IP4_PROTO_ICMP                 0x01
  56 #define IP4_CONFIG_INSTANCE_SIGNATURE  SIGNATURE_32 ('I', 'P', '4', 'C')
  57
  58 #define IP4_CONFIG_STATE_IDLE          0
  59 #define IP4_CONFIG_STATE_STARTED       1
  60 #define IP4_CONFIG_STATE_CONFIGURED    2
  61
  62 #define DHCP_TAG_PARA_LIST             55
  63 #define DHCP_TAG_NETMASK               1
  64 #define DHCP_TAG_ROUTER                3
  65
  66
  67 //
  68 // Configure the DHCP to request the routers and netmask
  69 // from server. The DHCP_TAG_NETMASK is included in Head.
  70 //
  71 #pragma pack(1)
  72 typedef struct {
  73   EFI_DHCP4_PACKET_OPTION Head;
  74   UINT8                   Route;
  75 } IP4_CONFIG_DHCP4_OPTION;
  76 #pragma pack()
  77
  78 typedef struct _IP4CONFIG_CALLBACK_INFO {
  79   BOOLEAN                          Configured;
  80   BOOLEAN                          DhcpEnabled;
  81   EFI_IPv4_ADDRESS                 LocalIp;
  82   EFI_IPv4_ADDRESS                 SubnetMask;
  83   EFI_IPv4_ADDRESS                 Gateway;
  84 } IP4_SETTING_INFO;
  85
  86 typedef struct _IP4_CONFIG_INSTANCE {
  87   UINT32                          Signature;
  88   EFI_HANDLE                      Controller;
  89   EFI_HANDLE                      Image;
  90   EFI_DEVICE_PATH_PROTOCOL        *ParentDevicePath;
  91
  92   EFI_IP4_CONFIG_PROTOCOL         Ip4ConfigProtocol;
  93
  94   EFI_HII_CONFIG_ACCESS_PROTOCOL  HiiConfigAccessProtocol;
  95   EFI_HANDLE                      ChildHandle;
  96   EFI_DEVICE_PATH_PROTOCOL        *HiiVendorDevicePath;
  97   EFI_HII_HANDLE                  RegisteredHandle;
  98   IP4_SETTING_INFO                Ip4ConfigCallbackInfo;
  99
 100   //
 101   // NicConfig's state, such as IP4_CONFIG_STATE_IDLE
 102   //
 103   INTN                            State;
 104
 105   //
 106   // Mnp child to keep the connection with MNP.
 107   //
 108   EFI_MANAGED_NETWORK_PROTOCOL    *Mnp;
 109   EFI_HANDLE                      MnpHandle;
 110
 111   //
 112   // User's requests data
 113   //
 114   EFI_EVENT                       DoneEvent;
 115   EFI_EVENT                       ReconfigEvent;
 116   EFI_STATUS                      Result;
 117
 118   //
 119   // Identity of this interface and some configuration info.
 120   //
 121   NIC_ADDR                        NicAddr;
 122   CHAR16                          *MacString;
 123   NIC_IP4_CONFIG_INFO             *NicConfig;
 124
 125   //
 126   // DHCP handles to access DHCP
 127   //
 128   EFI_DHCP4_PROTOCOL              *Dhcp4;
 129   EFI_HANDLE                      Dhcp4Handle;
 130   EFI_EVENT                       Dhcp4Event;
 131 } IP4_CONFIG_INSTANCE;
 132
 133 #define IP4_CONFIG_INSTANCE_FROM_IP4CONFIG(this) \
 134   CR (this, IP4_CONFIG_INSTANCE, Ip4ConfigProtocol, IP4_CONFIG_INSTANCE_SIGNATURE)
 135
 136 #define IP4_CONFIG_INSTANCE_FROM_CONFIG_ACCESS(this) \
 137   CR (this, IP4_CONFIG_INSTANCE, HiiConfigAccessProtocol, IP4_CONFIG_INSTANCE_SIGNATURE)
 138
 139
 140 /**
 141   Set the IP configure parameters for this NIC.
 142
 143   If Reconfig is TRUE, the IP driver will be informed to discard current
 144   auto configure parameter and restart the auto configuration process.
 145   If current there is a pending auto configuration, EFI_ALREADY_STARTED is
 146   returned. You can only change the configure setting when either
 147   the configure has finished or not started yet. If NicConfig, the
 148   NIC's configure parameter is removed from the variable.
 149
 150   @param  Instance               The IP4 CONFIG instance.
 151   @param  NicConfig              The new NIC IP4 configure parameter.
 152   @param  Reconfig               Inform the IP4 driver to restart the auto
 153                                  configuration.
 154
 155   @retval EFI_SUCCESS            The configure parameter for this NIC was
 156                                  set successfully.
 157   @retval EFI_INVALID_PARAMETER  This is NULL or the configure parameter is
 158                                  invalid.
 159   @retval EFI_ALREADY_STARTED    There is a pending auto configuration.
 160   @retval EFI_NOT_FOUND          No auto configure parameter is found.
 161
 162 **/
 163 EFI_STATUS
 164 EFIAPI
 165 EfiNicIp4ConfigSetInfo (
 166   IN IP4_CONFIG_INSTANCE          *Instance,
 167   IN NIC_IP4_CONFIG_INFO          *NicConfig     OPTIONAL,
 168   IN BOOLEAN                      Reconfig
 169   );
 170
 171 /**
 172   Get the NIC's configure information from the IP4 configure variable.
 173   It will remove the invalid variable.
 174
 175   @param  Instance               The IP4 CONFIG instance.
 176
 177   @return NULL if no configure for the NIC in the variable, or it is invalid.
 178           Otherwise the pointer to the NIC's IP configure parameter will be returned.
 179
 180 **/
 181 NIC_IP4_CONFIG_INFO *
 182 EfiNicIp4ConfigGetInfo (
 183   IN  IP4_CONFIG_INSTANCE   *Instance
 184   );
 185
 186 /**
 187   Release all the DHCP related resources.
 188
 189   @param  This                   The IP4 configure instance
 190
 191   @return None
 192
 193 **/
 194 VOID
 195 Ip4ConfigCleanDhcp4 (
 196   IN IP4_CONFIG_INSTANCE    *This
 197   );
 198
 199 /**
 200   Clean up all the configuration parameters.
 201
 202   @param  Instance               The IP4 configure instance
 203
 204   @return None
 205
 206 **/
 207 VOID
 208 Ip4ConfigCleanConfig (
 209   IN IP4_CONFIG_INSTANCE        *Instance
 210   );
 211
 212 //
 213 // EFI Component Name Functions
 214 //
 215
 216 /**
 217   Retrieves a Unicode string that is the user readable name of the driver.
 218
 219   This function retrieves the user readable name of a driver in the form of a
 220   Unicode string. If the driver specified by This has a user readable name in
 221   the language specified by Language, then a pointer to the driver name is
 222   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 223   by This does not support the language specified by Language,
 224   then EFI_UNSUPPORTED is returned.
 225
 226   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 227                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 228   @param  Language[in]          A pointer to a Null-terminated ASCII string
 229                                 array indicating the language. This is the
 230                                 language of the driver name that the caller is
 231                                 requesting, and it must match one of the
 232                                 languages specified in SupportedLanguages. The
 233                                 number of languages supported by a driver is up
 234                                 to the driver writer. Language is specified
 235                                 in RFC 3066 or ISO 639-2 language code format.
 236   @param  DriverName[out]       A pointer to the Unicode string to return.
 237                                 This Unicode string is the name of the
 238                                 driver specified by This in the language
 239                                 specified by Language.
 240
 241   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 242                                 This and the language specified by Language was
 243                                 returned in DriverName.
 244   @retval EFI_INVALID_PARAMETER Language is NULL.
 245   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 246   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 247                                 the language specified by Language.
 248
 249 **/
 250 EFI_STATUS
 251 EFIAPI
 252 Ip4ConfigComponentNameGetDriverName (
 253   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 254   IN  CHAR8                        *Language,
 255   OUT CHAR16                       **DriverName
 256   );
 257
 258 /**
 259   Retrieves a Unicode string that is the user readable name of the controller
 260   that is being managed by a driver.
 261
 262   This function retrieves the user readable name of the controller specified by
 263   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 264   driver specified by This has a user readable name in the language specified by
 265   Language, then a pointer to the controller name is returned in ControllerName,
 266   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 267   managing the controller specified by ControllerHandle and ChildHandle,
 268   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 269   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 270
 271   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 272                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 273   @param  ControllerHandle[in]  The handle of a controller that the driver
 274                                 specified by This is managing.  This handle
 275                                 specifies the controller whose name is to be
 276                                 returned.
 277   @param  ChildHandle[in]       The handle of the child controller to retrieve
 278                                 the name of.  This is an optional parameter that
 279                                 may be NULL.  It will be NULL for device
 280                                 drivers.  It will also be NULL for a bus drivers
 281                                 that wish to retrieve the name of the bus
 282                                 controller.  It will not be NULL for a bus
 283                                 driver that wishes to retrieve the name of a
 284                                 child controller.
 285   @param  Language[in]          A pointer to a Null-terminated ASCII string
 286                                 array indicating the language.  This is the
 287                                 language of the driver name that the caller is
 288                                 requesting, and it must match one of the
 289                                 languages specified in SupportedLanguages. The
 290                                 number of languages supported by a driver is up
 291                                 to the driver writer. Language is specified in
 292                                 RFC 3066 or ISO 639-2 language code format.
 293   @param  ControllerName[out]   A pointer to the Unicode string to return.
 294                                 This Unicode string is the name of the
 295                                 controller specified by ControllerHandle and
 296                                 ChildHandle in the language specified by
 297                                 Language from the point of view of the driver
 298                                 specified by This.
 299
 300   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 301                                 the language specified by Language for the
 302                                 driver specified by This was returned in
 303                                 DriverName.
 304   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
 305   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 306                                 EFI_HANDLE.
 307   @retval EFI_INVALID_PARAMETER Language is NULL.
 308   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 309   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 310                                 managing the controller specified by
 311                                 ControllerHandle and ChildHandle.
 312   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 313                                 the language specified by Language.
 314
 315 **/
 316 EFI_STATUS
 317 EFIAPI
 318 Ip4ConfigComponentNameGetControllerName (
 319   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 320   IN  EFI_HANDLE                                      ControllerHandle,
 321   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 322   IN  CHAR8                                           *Language,
 323   OUT CHAR16                                          **ControllerName
 324   );
 325
 326 /**
 327   Test to see if this driver supports ControllerHandle.
 328
 329   @param  This                 Protocol instance pointer.
 330   @param  ControllerHandle     Handle of device to test
 331   @param  RemainingDevicePath  Optional parameter use to pick a specific child
 332                                device to start.
 333
 334   @retval EFI_SUCCES           This driver supports this device
 335   @retval EFI_ALREADY_STARTED  This driver is already running on this device
 336   @retval other                This driver does not support this device
 337
 338 **/
 339 EFI_STATUS
 340 EFIAPI
 341 Ip4ConfigDriverBindingSupported (
 342   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 343   IN EFI_HANDLE                   ControllerHandle,
 344   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath  OPTIONAL
 345   );
 346
 347 /**
 348   Start this driver on ControllerHandle.
 349
 350   @param  This                 Protocol instance pointer.
 351   @param  ControllerHandle     Handle of device to bind driver to
 352   @param  RemainingDevicePath  Optional parameter use to pick a specific child
 353                                device to start.
 354
 355   @retval EFI_SUCCES           This driver is added to ControllerHandle
 356   @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle
 357   @retval other                This driver does not support this device
 358
 359 **/
 360 EFI_STATUS
 361 EFIAPI
 362 Ip4ConfigDriverBindingStart (
 363   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 364   IN EFI_HANDLE                   ControllerHandle,
 365   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 366   );
 367
 368 /**
 369   Stop this driver on ControllerHandle.
 370
 371   @param  This                 Protocol instance pointer.
 372   @param  ControllerHandle     Handle of device to stop driver on
 373   @param  NumberOfChildren     Number of Handles in ChildHandleBuffer. If number of
 374                                 children is zero stop the entire bus driver.
 375   @param  ChildHandleBuffer    List of Child Handles to Stop.
 376
 377   @retval EFI_SUCCES           This driver is removed ControllerHandle
 378   @retval other                This driver was not removed from this device
 379
 380 **/
 381 EFI_STATUS
 382 EFIAPI
 383 Ip4ConfigDriverBindingStop (
 384   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 385   IN EFI_HANDLE                   ControllerHandle,
 386   IN UINTN                        NumberOfChildren,
 387   IN EFI_HANDLE                   *ChildHandleBuffer
 388   );
 389
 390 /**
 391   Starts running the configuration policy for the EFI IPv4 Protocol driver.
 392
 393   The Start() function is called to determine and to begin the platform
 394   configuration policy by the EFI IPv4 Protocol driver. This determination may
 395   be as simple as returning EFI_UNSUPPORTED if there is no EFI IPv4 Protocol
 396   driver configuration policy. It may be as involved as loading some defaults
 397   from nonvolatile storage, downloading dynamic data from a DHCP server, and
 398   checking permissions with a site policy server.
 399   Starting the configuration policy is just the beginning. It may finish almost
 400   instantly or it may take several minutes before it fails to retrieve configuration
 401   information from one or more servers. Once the policy is started, drivers
 402   should use the DoneEvent parameter to determine when the configuration policy
 403   has completed. EFI_IP4_CONFIG_PROTOCOL.GetData() must then be called to
 404   determine if the configuration succeeded or failed.
 405   Until the configuration completes successfully, EFI IPv4 Protocol driver instances
 406   that are attempting to use default configurations must return EFI_NO_MAPPING.
 407   Once the configuration is complete, the EFI IPv4 Configuration Protocol driver
 408   signals DoneEvent. The configuration may need to be updated in the future,
 409   however; in this case, the EFI IPv4 Configuration Protocol driver must signal
 410   ReconfigEvent, and all EFI IPv4 Protocol driver instances that are using default
 411   configurations must return EFI_NO_MAPPING until the configuration policy has
 412   been rerun.
 413
 414   @param  This                   Pointer to the EFI_IP4_CONFIG_PROTOCOL instance.
 415   @param  DoneEvent              Event that will be signaled when the EFI IPv4
 416                                  Protocol driver configuration policy completes
 417                                  execution. This event must be of type EVT_NOTIFY_SIGNAL.
 418   @param  ReconfigEvent          Event that will be signaled when the EFI IPv4
 419                                  Protocol driver configuration needs to be updated.
 420                                  This event must be of type EVT_NOTIFY_SIGNAL.
 421
 422   @retval EFI_SUCCESS            The configuration policy for the EFI IPv4 Protocol
 423                                  driver is now running.
 424   @retval EFI_INVALID_PARAMETER  One or more of the following parameters is NULL:
 425                                   This
 426                                   DoneEvent
 427                                   ReconfigEvent
 428   @retval EFI_OUT_OF_RESOURCES   Required system resources could not be allocated.
 429   @retval EFI_ALREADY_STARTED    The configuration policy for the EFI IPv4 Protocol
 430                                  driver was already started.
 431   @retval EFI_DEVICE_ERROR       An unexpected system error or network error occurred.
 432   @retval EFI_UNSUPPORTED        This interface does not support the EFI IPv4 Protocol
 433                                  driver configuration.
 434
 435 **/
 436 EFI_STATUS
 437 EFIAPI
 438 EfiIp4ConfigStart (
 439   IN EFI_IP4_CONFIG_PROTOCOL  *This,
 440   IN EFI_EVENT                DoneEvent,
 441   IN EFI_EVENT                ReconfigEvent
 442   );
 443
 444 /**
 445   Stops running the configuration policy for the EFI IPv4 Protocol driver.
 446
 447   The Stop() function stops the configuration policy for the EFI IPv4 Protocol driver.
 448   All configuration data will be lost after calling Stop().
 449
 450   @param  This                   Pointer to the EFI_IP4_CONFIG_PROTOCOL instance.
 451
 452   @retval EFI_SUCCESS            The configuration policy for the EFI IPv4 Protocol
 453                                  driver has been stopped.
 454   @retval EFI_INVALID_PARAMETER  This is NULL.
 455   @retval EFI_NOT_STARTED        The configuration policy for the EFI IPv4 Protocol
 456                                  driver was not started.
 457
 458 **/
 459 EFI_STATUS
 460 EFIAPI
 461 EfiIp4ConfigStop (
 462   IN EFI_IP4_CONFIG_PROTOCOL  *This
 463   );
 464
 465 /**
 466   Returns the default configuration data (if any) for the EFI IPv4 Protocol driver.
 467
 468   The GetData() function returns the current configuration data for the EFI IPv4
 469   Protocol driver after the configuration policy has completed.
 470
 471   @param  This                   Pointer to the EFI_IP4_CONFIG_PROTOCOL instance.
 472   @param  ConfigDataSize         On input, the size of the ConfigData buffer.
 473                                  On output, the count of bytes that were written
 474                                  into the ConfigData buffer.
 475   @param  ConfigData             Pointer to the EFI IPv4 Configuration Protocol
 476                                  driver configuration data structure.
 477                                  Type EFI_IP4_IPCONFIG_DATA is defined in
 478                                  "Related Definitions" below.
 479
 480   @retval EFI_SUCCESS            The EFI IPv4 Protocol driver configuration has been returned.
 481   @retval EFI_INVALID_PARAMETER  This is NULL.
 482   @retval EFI_NOT_STARTED        The configuration policy for the EFI IPv4 Protocol
 483                                  driver is not running.
 484   @retval EFI_NOT_READY          EFI IPv4 Protocol driver configuration is still running.
 485   @retval EFI_ABORTED            EFI IPv4 Protocol driver configuration could not complete.
 486                                  Currently not implemented.
 487   @retval EFI_BUFFER_TOO_SMALL   *ConfigDataSize is smaller than the configuration
 488                                  data buffer or ConfigData is NULL.
 489
 490 **/
 491 EFI_STATUS
 492 EFIAPI
 493 EfiIp4ConfigGetData (
 494   IN  EFI_IP4_CONFIG_PROTOCOL *This,
 495   IN  OUT  UINTN              *ConfigDataSize,
 496   OUT EFI_IP4_IPCONFIG_DATA   *ConfigData           OPTIONAL
 497   );
 498
 499 #endif