MdeModulePkg/Universal/Network/Ip4ConfigDxe/Ip4Config.h

   1 /** @file
   2   Header file for IP4Config driver.
   3
   4 Copyright (c) 2006 - 2011, 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
 132   //
 133   // A dedicated timer is used to poll underlying media status
 134   //
 135   EFI_EVENT                       Timer;
 136
 137   //
 138   // Underlying media present status.
 139   //
 140   BOOLEAN                         MediaPresent;
 141 } IP4_CONFIG_INSTANCE;
 142
 143 #define IP4_CONFIG_INSTANCE_FROM_IP4CONFIG(this) \
 144   CR (this, IP4_CONFIG_INSTANCE, Ip4ConfigProtocol, IP4_CONFIG_INSTANCE_SIGNATURE)
 145
 146 #define IP4_CONFIG_INSTANCE_FROM_CONFIG_ACCESS(this) \
 147   CR (this, IP4_CONFIG_INSTANCE, HiiConfigAccessProtocol, IP4_CONFIG_INSTANCE_SIGNATURE)
 148
 149
 150 /**
 151   Set the IP configure parameters for this NIC.
 152
 153   If Reconfig is TRUE, the IP driver will be informed to discard current
 154   auto configure parameter and restart the auto configuration process.
 155   If current there is a pending auto configuration, EFI_ALREADY_STARTED is
 156   returned. You can only change the configure setting when either
 157   the configure has finished or not started yet. If NicConfig, the
 158   NIC's configure parameter is removed from the variable.
 159
 160   @param  Instance               The IP4 CONFIG instance.
 161   @param  NicConfig              The new NIC IP4 configure parameter.
 162   @param  Reconfig               Inform the IP4 driver to restart the auto
 163                                  configuration.
 164
 165   @retval EFI_SUCCESS            The configure parameter for this NIC was
 166                                  set successfully.
 167   @retval EFI_INVALID_PARAMETER  This is NULL or the configure parameter is
 168                                  invalid.
 169   @retval EFI_ALREADY_STARTED    There is a pending auto configuration.
 170   @retval EFI_NOT_FOUND          No auto configure parameter is found.
 171
 172 **/
 173 EFI_STATUS
 174 EFIAPI
 175 EfiNicIp4ConfigSetInfo (
 176   IN IP4_CONFIG_INSTANCE          *Instance,
 177   IN NIC_IP4_CONFIG_INFO          *NicConfig     OPTIONAL,
 178   IN BOOLEAN                      Reconfig
 179   );
 180
 181 /**
 182   Get the NIC's configure information from the IP4 configure variable.
 183   It will remove the invalid variable.
 184
 185   @param  Instance               The IP4 CONFIG instance.
 186
 187   @return NULL if no configure for the NIC in the variable, or it is invalid.
 188           Otherwise the pointer to the NIC's IP configure parameter will be returned.
 189
 190 **/
 191 NIC_IP4_CONFIG_INFO *
 192 EfiNicIp4ConfigGetInfo (
 193   IN  IP4_CONFIG_INSTANCE   *Instance
 194   );
 195
 196 /**
 197   Release all the DHCP related resources.
 198
 199   @param  This                   The IP4 configure instance
 200
 201   @return None
 202
 203 **/
 204 VOID
 205 Ip4ConfigCleanDhcp4 (
 206   IN IP4_CONFIG_INSTANCE    *This
 207   );
 208
 209 /**
 210   Clean up all the configuration parameters.
 211
 212   @param  Instance               The IP4 configure instance
 213
 214   @return None
 215
 216 **/
 217 VOID
 218 Ip4ConfigCleanConfig (
 219   IN IP4_CONFIG_INSTANCE        *Instance
 220   );
 221
 222 //
 223 // EFI Component Name Functions
 224 //
 225
 226 /**
 227   Retrieves a Unicode string that is the user readable name of the driver.
 228
 229   This function retrieves the user readable name of a driver in the form of a
 230   Unicode string. If the driver specified by This has a user readable name in
 231   the language specified by Language, then a pointer to the driver name is
 232   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 233   by This does not support the language specified by Language,
 234   then EFI_UNSUPPORTED is returned.
 235
 236   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 237                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 238   @param  Language[in]          A pointer to a Null-terminated ASCII string
 239                                 array indicating the language. This is the
 240                                 language of the driver name that the caller is
 241                                 requesting, and it must match one of the
 242                                 languages specified in SupportedLanguages. The
 243                                 number of languages supported by a driver is up
 244                                 to the driver writer. Language is specified
 245                                 in RFC 3066 or ISO 639-2 language code format.
 246   @param  DriverName[out]       A pointer to the Unicode string to return.
 247                                 This Unicode string is the name of the
 248                                 driver specified by This in the language
 249                                 specified by Language.
 250
 251   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 252                                 This and the language specified by Language was
 253                                 returned in DriverName.
 254   @retval EFI_INVALID_PARAMETER Language is NULL.
 255   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 256   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 257                                 the language specified by Language.
 258
 259 **/
 260 EFI_STATUS
 261 EFIAPI
 262 Ip4ConfigComponentNameGetDriverName (
 263   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 264   IN  CHAR8                        *Language,
 265   OUT CHAR16                       **DriverName
 266   );
 267
 268 /**
 269   Retrieves a Unicode string that is the user readable name of the controller
 270   that is being managed by a driver.
 271
 272   This function retrieves the user readable name of the controller specified by
 273   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 274   driver specified by This has a user readable name in the language specified by
 275   Language, then a pointer to the controller name is returned in ControllerName,
 276   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 277   managing the controller specified by ControllerHandle and ChildHandle,
 278   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 279   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 280
 281   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 282                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 283   @param  ControllerHandle[in]  The handle of a controller that the driver
 284                                 specified by This is managing.  This handle
 285                                 specifies the controller whose name is to be
 286                                 returned.
 287   @param  ChildHandle[in]       The handle of the child controller to retrieve
 288                                 the name of.  This is an optional parameter that
 289                                 may be NULL.  It will be NULL for device
 290                                 drivers.  It will also be NULL for a bus drivers
 291                                 that wish to retrieve the name of the bus
 292                                 controller.  It will not be NULL for a bus
 293                                 driver that wishes to retrieve the name of a
 294                                 child controller.
 295   @param  Language[in]          A pointer to a Null-terminated ASCII string
 296                                 array indicating the language.  This is the
 297                                 language of the driver name that the caller is
 298                                 requesting, and it must match one of the
 299                                 languages specified in SupportedLanguages. The
 300                                 number of languages supported by a driver is up
 301                                 to the driver writer. Language is specified in
 302                                 RFC 3066 or ISO 639-2 language code format.
 303   @param  ControllerName[out]   A pointer to the Unicode string to return.
 304                                 This Unicode string is the name of the
 305                                 controller specified by ControllerHandle and
 306                                 ChildHandle in the language specified by
 307                                 Language from the point of view of the driver
 308                                 specified by This.
 309
 310   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 311                                 the language specified by Language for the
 312                                 driver specified by This was returned in
 313                                 DriverName.
 314   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
 315   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 316                                 EFI_HANDLE.
 317   @retval EFI_INVALID_PARAMETER Language is NULL.
 318   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 319   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 320                                 managing the controller specified by
 321                                 ControllerHandle and ChildHandle.
 322   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 323                                 the language specified by Language.
 324
 325 **/
 326 EFI_STATUS
 327 EFIAPI
 328 Ip4ConfigComponentNameGetControllerName (
 329   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 330   IN  EFI_HANDLE                                      ControllerHandle,
 331   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 332   IN  CHAR8                                           *Language,
 333   OUT CHAR16                                          **ControllerName
 334   );
 335
 336 /**
 337   Test to see if this driver supports ControllerHandle.
 338
 339   @param  This                 Protocol instance pointer.
 340   @param  ControllerHandle     Handle of device to test
 341   @param  RemainingDevicePath  Optional parameter use to pick a specific child
 342                                device to start.
 343
 344   @retval EFI_SUCCES           This driver supports this device
 345   @retval EFI_ALREADY_STARTED  This driver is already running on this device
 346   @retval other                This driver does not support this device
 347
 348 **/
 349 EFI_STATUS
 350 EFIAPI
 351 Ip4ConfigDriverBindingSupported (
 352   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 353   IN EFI_HANDLE                   ControllerHandle,
 354   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath  OPTIONAL
 355   );
 356
 357 /**
 358   Start this driver on ControllerHandle.
 359
 360   @param  This                 Protocol instance pointer.
 361   @param  ControllerHandle     Handle of device to bind driver to
 362   @param  RemainingDevicePath  Optional parameter use to pick a specific child
 363                                device to start.
 364
 365   @retval EFI_SUCCES           This driver is added to ControllerHandle
 366   @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle
 367   @retval other                This driver does not support this device
 368
 369 **/
 370 EFI_STATUS
 371 EFIAPI
 372 Ip4ConfigDriverBindingStart (
 373   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 374   IN EFI_HANDLE                   ControllerHandle,
 375   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 376   );
 377
 378 /**
 379   Stop this driver on ControllerHandle.
 380
 381   @param  This                 Protocol instance pointer.
 382   @param  ControllerHandle     Handle of device to stop driver on
 383   @param  NumberOfChildren     Number of Handles in ChildHandleBuffer. If number of
 384                                 children is zero stop the entire bus driver.
 385   @param  ChildHandleBuffer    List of Child Handles to Stop.
 386
 387   @retval EFI_SUCCES           This driver is removed ControllerHandle
 388   @retval other                This driver was not removed from this device
 389
 390 **/
 391 EFI_STATUS
 392 EFIAPI
 393 Ip4ConfigDriverBindingStop (
 394   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 395   IN EFI_HANDLE                   ControllerHandle,
 396   IN UINTN                        NumberOfChildren,
 397   IN EFI_HANDLE                   *ChildHandleBuffer
 398   );
 399
 400 /**
 401   Starts running the configuration policy for the EFI IPv4 Protocol driver.
 402
 403   The Start() function is called to determine and to begin the platform
 404   configuration policy by the EFI IPv4 Protocol driver. This determination may
 405   be as simple as returning EFI_UNSUPPORTED if there is no EFI IPv4 Protocol
 406   driver configuration policy. It may be as involved as loading some defaults
 407   from nonvolatile storage, downloading dynamic data from a DHCP server, and
 408   checking permissions with a site policy server.
 409   Starting the configuration policy is just the beginning. It may finish almost
 410   instantly or it may take several minutes before it fails to retrieve configuration
 411   information from one or more servers. Once the policy is started, drivers
 412   should use the DoneEvent parameter to determine when the configuration policy
 413   has completed. EFI_IP4_CONFIG_PROTOCOL.GetData() must then be called to
 414   determine if the configuration succeeded or failed.
 415   Until the configuration completes successfully, EFI IPv4 Protocol driver instances
 416   that are attempting to use default configurations must return EFI_NO_MAPPING.
 417   Once the configuration is complete, the EFI IPv4 Configuration Protocol driver
 418   signals DoneEvent. The configuration may need to be updated in the future,
 419   however; in this case, the EFI IPv4 Configuration Protocol driver must signal
 420   ReconfigEvent, and all EFI IPv4 Protocol driver instances that are using default
 421   configurations must return EFI_NO_MAPPING until the configuration policy has
 422   been rerun.
 423
 424   @param  This                   Pointer to the EFI_IP4_CONFIG_PROTOCOL instance.
 425   @param  DoneEvent              Event that will be signaled when the EFI IPv4
 426                                  Protocol driver configuration policy completes
 427                                  execution. This event must be of type EVT_NOTIFY_SIGNAL.
 428   @param  ReconfigEvent          Event that will be signaled when the EFI IPv4
 429                                  Protocol driver configuration needs to be updated.
 430                                  This event must be of type EVT_NOTIFY_SIGNAL.
 431
 432   @retval EFI_SUCCESS            The configuration policy for the EFI IPv4 Protocol
 433                                  driver is now running.
 434   @retval EFI_INVALID_PARAMETER  One or more of the following parameters is NULL:
 435                                   This
 436                                   DoneEvent
 437                                   ReconfigEvent
 438   @retval EFI_OUT_OF_RESOURCES   Required system resources could not be allocated.
 439   @retval EFI_ALREADY_STARTED    The configuration policy for the EFI IPv4 Protocol
 440                                  driver was already started.
 441   @retval EFI_DEVICE_ERROR       An unexpected system error or network error occurred.
 442   @retval EFI_UNSUPPORTED        This interface does not support the EFI IPv4 Protocol
 443                                  driver configuration.
 444
 445 **/
 446 EFI_STATUS
 447 EFIAPI
 448 EfiIp4ConfigStart (
 449   IN EFI_IP4_CONFIG_PROTOCOL  *This,
 450   IN EFI_EVENT                DoneEvent,
 451   IN EFI_EVENT                ReconfigEvent
 452   );
 453
 454 /**
 455   Stops running the configuration policy for the EFI IPv4 Protocol driver.
 456
 457   The Stop() function stops the configuration policy for the EFI IPv4 Protocol driver.
 458   All configuration data will be lost after calling Stop().
 459
 460   @param  This                   Pointer to the EFI_IP4_CONFIG_PROTOCOL instance.
 461
 462   @retval EFI_SUCCESS            The configuration policy for the EFI IPv4 Protocol
 463                                  driver has been stopped.
 464   @retval EFI_INVALID_PARAMETER  This is NULL.
 465   @retval EFI_NOT_STARTED        The configuration policy for the EFI IPv4 Protocol
 466                                  driver was not started.
 467
 468 **/
 469 EFI_STATUS
 470 EFIAPI
 471 EfiIp4ConfigStop (
 472   IN EFI_IP4_CONFIG_PROTOCOL  *This
 473   );
 474
 475 /**
 476   Returns the default configuration data (if any) for the EFI IPv4 Protocol driver.
 477
 478   The GetData() function returns the current configuration data for the EFI IPv4
 479   Protocol driver after the configuration policy has completed.
 480
 481   @param  This                   Pointer to the EFI_IP4_CONFIG_PROTOCOL instance.
 482   @param  ConfigDataSize         On input, the size of the ConfigData buffer.
 483                                  On output, the count of bytes that were written
 484                                  into the ConfigData buffer.
 485   @param  ConfigData             Pointer to the EFI IPv4 Configuration Protocol
 486                                  driver configuration data structure.
 487                                  Type EFI_IP4_IPCONFIG_DATA is defined in
 488                                  "Related Definitions" below.
 489
 490   @retval EFI_SUCCESS            The EFI IPv4 Protocol driver configuration has been returned.
 491   @retval EFI_INVALID_PARAMETER  This is NULL.
 492   @retval EFI_NOT_STARTED        The configuration policy for the EFI IPv4 Protocol
 493                                  driver is not running.
 494   @retval EFI_NOT_READY          EFI IPv4 Protocol driver configuration is still running.
 495   @retval EFI_ABORTED            EFI IPv4 Protocol driver configuration could not complete.
 496                                  Currently not implemented.
 497   @retval EFI_BUFFER_TOO_SMALL   *ConfigDataSize is smaller than the configuration
 498                                  data buffer or ConfigData is NULL.
 499
 500 **/
 501 EFI_STATUS
 502 EFIAPI
 503 EfiIp4ConfigGetData (
 504   IN  EFI_IP4_CONFIG_PROTOCOL *This,
 505   IN  OUT  UINTN              *ConfigDataSize,
 506   OUT EFI_IP4_IPCONFIG_DATA   *ConfigData           OPTIONAL
 507   );
 508
 509 /**
 510   A dedicated timer is used to poll underlying media status. In case of
 511   cable swap, a new round auto configuration will be initiated. The timer
 512   will signal the IP4 to run the auto configuration again. IP4 driver will free
 513   old IP address related resource, such as route table and Interface, then
 514   initiate a DHCP round by IP4Config->Start to acquire new IP, eventually
 515   create route table for new IP address.
 516
 517   @param[in]  Event                  The IP4 service instance's heart beat timer.
 518   @param[in]  Context                The IP4 service instance.
 519
 520 **/
 521 VOID
 522 EFIAPI
 523 MediaChangeDetect (
 524   IN EFI_EVENT              Event,
 525   IN VOID                   *Context
 526   );
 527
 528 #endif