iPXE
Ip4Config.h
Go to the documentation of this file.
00001 /** @file
00002   This file provides a definition of the EFI IPv4 Configuration
00003   Protocol.
00004 
00005 Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR>
00006 This program and the accompanying materials are licensed and made available under
00007 the terms and conditions of the BSD License that accompanies this distribution.
00008 The full text of the license may be found at
00009 http://opensource.org/licenses/bsd-license.php.
00010 
00011 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00012 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00013 
00014   @par Revision Reference:
00015   This Protocol is introduced in UEFI Specification 2.0.
00016 
00017 **/
00018 #ifndef __EFI_IP4CONFIG_PROTOCOL_H__
00019 #define __EFI_IP4CONFIG_PROTOCOL_H__
00020 
00021 FILE_LICENCE ( BSD3 );
00022 
00023 #include <ipxe/efi/Protocol/Ip4.h>
00024 
00025 #define EFI_IP4_CONFIG_PROTOCOL_GUID \
00026   { \
00027     0x3b95aa31, 0x3793, 0x434b, {0x86, 0x67, 0xc8, 0x07, 0x08, 0x92, 0xe0, 0x5e } \
00028   }
00029 
00030 typedef struct _EFI_IP4_CONFIG_PROTOCOL EFI_IP4_CONFIG_PROTOCOL;
00031 
00032 #define IP4_CONFIG_VARIABLE_ATTRIBUTES \
00033         (EFI_VARIABLE_NON_VOLATILE | EFI_VARIABLE_BOOTSERVICE_ACCESS)
00034 
00035 ///
00036 /// EFI_IP4_IPCONFIG_DATA contains the minimum IPv4 configuration data
00037 /// that is needed to start basic network communication. The StationAddress
00038 /// and SubnetMask must be a valid unicast IP address and subnet mask.
00039 /// If RouteTableSize is not zero, then RouteTable contains a properly
00040 /// formatted routing table for the StationAddress/SubnetMask, with the
00041 /// last entry in the table being the default route.
00042 ///
00043 typedef struct {
00044   ///
00045   /// Default station IP address, stored in network byte order.
00046   ///
00047   EFI_IPv4_ADDRESS             StationAddress;
00048   ///
00049   /// Default subnet mask, stored in network byte order.
00050   ///
00051   EFI_IPv4_ADDRESS             SubnetMask;
00052   ///
00053   /// Number of entries in the following RouteTable. May be zero.
00054   ///
00055   UINT32                       RouteTableSize;
00056   ///
00057   /// Default routing table data (stored in network byte order).
00058   /// Ignored if RouteTableSize is zero.
00059   ///
00060   EFI_IP4_ROUTE_TABLE          *RouteTable;
00061 } EFI_IP4_IPCONFIG_DATA;
00062 
00063 
00064 /**
00065   Starts running the configuration policy for the EFI IPv4 Protocol driver.
00066 
00067   The Start() function is called to determine and to begin the platform
00068   configuration policy by the EFI IPv4 Protocol driver. This determination may
00069   be as simple as returning EFI_UNSUPPORTED if there is no EFI IPv4 Protocol
00070   driver configuration policy. It may be as involved as loading some defaults
00071   from nonvolatile storage, downloading dynamic data from a DHCP server, and
00072   checking permissions with a site policy server.
00073   Starting the configuration policy is just the beginning. It may finish almost
00074   instantly or it may take several minutes before it fails to retrieve configuration
00075   information from one or more servers. Once the policy is started, drivers
00076   should use the DoneEvent parameter to determine when the configuration policy
00077   has completed. EFI_IP4_CONFIG_PROTOCOL.GetData() must then be called to
00078   determine if the configuration succeeded or failed.
00079   Until the configuration completes successfully, EFI IPv4 Protocol driver instances
00080   that are attempting to use default configurations must return EFI_NO_MAPPING.
00081   Once the configuration is complete, the EFI IPv4 Configuration Protocol driver
00082   signals DoneEvent. The configuration may need to be updated in the future.
00083   Note that in this case the EFI IPv4 Configuration Protocol driver must signal
00084   ReconfigEvent, and all EFI IPv4 Protocol driver instances that are using default
00085   configurations must return EFI_NO_MAPPING until the configuration policy has
00086   been rerun.
00087 
00088   @param  This                   The pointer to the EFI_IP4_CONFIG_PROTOCOL instance.
00089   @param  DoneEvent              Event that will be signaled when the EFI IPv4
00090                                  Protocol driver configuration policy completes
00091                                  execution. This event must be of type EVT_NOTIFY_SIGNAL.
00092   @param  ReconfigEvent          Event that will be signaled when the EFI IPv4
00093                                  Protocol driver configuration needs to be updated.
00094                                  This event must be of type EVT_NOTIFY_SIGNAL.
00095 
00096   @retval EFI_SUCCESS            The configuration policy for the EFI IPv4 Protocol
00097                                  driver is now running.
00098   @retval EFI_INVALID_PARAMETER  One or more of the following parameters is NULL:
00099                                   This
00100                                   DoneEvent
00101                                   ReconfigEvent
00102   @retval EFI_OUT_OF_RESOURCES   Required system resources could not be allocated.
00103   @retval EFI_ALREADY_STARTED    The configuration policy for the EFI IPv4 Protocol
00104                                  driver was already started.
00105   @retval EFI_DEVICE_ERROR       An unexpected system error or network error occurred.
00106   @retval EFI_UNSUPPORTED        This interface does not support the EFI IPv4 Protocol
00107                                  driver configuration.
00108 
00109 **/
00110 typedef
00111 EFI_STATUS
00112 (EFIAPI *EFI_IP4_CONFIG_START)(
00113   IN EFI_IP4_CONFIG_PROTOCOL   *This,
00114   IN EFI_EVENT                 DoneEvent,
00115   IN EFI_EVENT                 ReconfigEvent
00116   );
00117 
00118 /**
00119   Stops running the configuration policy for the EFI IPv4 Protocol driver.
00120 
00121   The Stop() function stops the configuration policy for the EFI IPv4 Protocol driver.
00122   All configuration data will be lost after calling Stop().
00123 
00124   @param  This                   The pointer to the EFI_IP4_CONFIG_PROTOCOL instance.
00125 
00126   @retval EFI_SUCCESS            The configuration policy for the EFI IPv4 Protocol
00127                                  driver has been stopped.
00128   @retval EFI_INVALID_PARAMETER  This is NULL.
00129   @retval EFI_NOT_STARTED        The configuration policy for the EFI IPv4 Protocol
00130                                  driver was not started.
00131 
00132 **/
00133 typedef
00134 EFI_STATUS
00135 (EFIAPI *EFI_IP4_CONFIG_STOP)(
00136   IN EFI_IP4_CONFIG_PROTOCOL   *This
00137   );
00138 
00139 /**
00140   Returns the default configuration data (if any) for the EFI IPv4 Protocol driver.
00141 
00142   The GetData() function returns the current configuration data for the EFI IPv4
00143   Protocol driver after the configuration policy has completed.
00144 
00145   @param  This                   The pointer to the EFI_IP4_CONFIG_PROTOCOL instance.
00146   @param  IpConfigDataSize       On input, the size of the IpConfigData buffer.
00147                                  On output, the count of bytes that were written
00148                                  into the IpConfigData buffer.
00149   @param  IpConfigData           The pointer to the EFI IPv4 Configuration Protocol
00150                                  driver configuration data structure.
00151                                  Type EFI_IP4_IPCONFIG_DATA is defined in
00152                                  "Related Definitions" below.
00153 
00154   @retval EFI_SUCCESS            The EFI IPv4 Protocol driver configuration has been returned.
00155   @retval EFI_INVALID_PARAMETER  This is NULL.
00156   @retval EFI_NOT_STARTED        The configuration policy for the EFI IPv4 Protocol
00157                                  driver is not running.
00158   @retval EFI_NOT_READY EFI      IPv4 Protocol driver configuration is still running.
00159   @retval EFI_ABORTED EFI        IPv4 Protocol driver configuration could not complete.
00160   @retval EFI_BUFFER_TOO_SMALL   *IpConfigDataSize is smaller than the configuration
00161                                  data buffer or IpConfigData is NULL.
00162 
00163 **/
00164 typedef
00165 EFI_STATUS
00166 (EFIAPI *EFI_IP4_CONFIG_GET_DATA)(
00167   IN EFI_IP4_CONFIG_PROTOCOL   *This,
00168   IN OUT UINTN                 *IpConfigDataSize,
00169   OUT EFI_IP4_IPCONFIG_DATA    *IpConfigData    OPTIONAL
00170   );
00171 
00172 ///
00173 /// The EFI_IP4_CONFIG_PROTOCOL driver performs platform-dependent and policy-dependent
00174 /// configurations for the EFI IPv4 Protocol driver.
00175 ///
00176 struct _EFI_IP4_CONFIG_PROTOCOL {
00177   EFI_IP4_CONFIG_START         Start;
00178   EFI_IP4_CONFIG_STOP          Stop;
00179   EFI_IP4_CONFIG_GET_DATA      GetData;
00180 };
00181 
00182 extern EFI_GUID gEfiIp4ConfigProtocolGuid;
00183 
00184 #endif