MdeModulePkg/Universal/Network/Ip4ConfigDxe/Ip4Config.h

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