iPXE
ManagedNetwork.h
Go to the documentation of this file.
00001 /** @file
00002   EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL as defined in UEFI 2.0.
00003   EFI_MANAGED_NETWORK_PROTOCOL as defined in UEFI 2.0.
00004 
00005 Copyright (c) 2006 - 2010, 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 
00019 #ifndef __EFI_MANAGED_NETWORK_PROTOCOL_H__
00020 #define __EFI_MANAGED_NETWORK_PROTOCOL_H__
00021 
00022 FILE_LICENCE ( BSD3 );
00023 
00024 #include <ipxe/efi/Protocol/SimpleNetwork.h>
00025 
00026 #define EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL_GUID \
00027   { \
00028     0xf36ff770, 0xa7e1, 0x42cf, {0x9e, 0xd2, 0x56, 0xf0, 0xf2, 0x71, 0xf4, 0x4c } \
00029   }
00030 
00031 #define EFI_MANAGED_NETWORK_PROTOCOL_GUID \
00032   { \
00033     0x7ab33a91, 0xace5, 0x4326, { 0xb5, 0x72, 0xe7, 0xee, 0x33, 0xd3, 0x9f, 0x16 } \
00034   }
00035 
00036 typedef struct _EFI_MANAGED_NETWORK_PROTOCOL EFI_MANAGED_NETWORK_PROTOCOL;
00037 
00038 typedef struct {
00039   ///
00040   /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed
00041   /// from the MNP receive queue will be dropped if its receive timeout expires.
00042   ///
00043   UINT32     ReceivedQueueTimeoutValue;
00044   ///
00045   /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed
00046   /// from the MNP transmit queue will be dropped if its receive timeout expires.
00047   ///
00048   UINT32     TransmitQueueTimeoutValue;
00049   ///
00050   /// Ethernet type II 16-bit protocol type in host byte order. Valid
00051   /// values are zero and 1,500 to 65,535.
00052   ///
00053   UINT16     ProtocolTypeFilter;
00054   ///
00055   /// Set to TRUE to receive packets that are sent to the network
00056   /// device MAC address. The startup default value is FALSE.
00057   ///
00058   BOOLEAN    EnableUnicastReceive;
00059   ///
00060   /// Set to TRUE to receive packets that are sent to any of the
00061   /// active multicast groups. The startup default value is FALSE.
00062   ///
00063   BOOLEAN    EnableMulticastReceive;
00064   ///
00065   /// Set to TRUE to receive packets that are sent to the network
00066   /// device broadcast address. The startup default value is FALSE.
00067   ///
00068   BOOLEAN    EnableBroadcastReceive;
00069   ///
00070   /// Set to TRUE to receive packets that are sent to any MAC address.
00071   /// The startup default value is FALSE.
00072   ///
00073   BOOLEAN    EnablePromiscuousReceive;
00074   ///
00075   /// Set to TRUE to drop queued packets when the configuration
00076   /// is changed. The startup default value is FALSE.
00077   ///
00078   BOOLEAN    FlushQueuesOnReset;
00079   ///
00080   /// Set to TRUE to timestamp all packets when they are received
00081   /// by the MNP. Note that timestamps may be unsupported in some
00082   /// MNP implementations. The startup default value is FALSE.
00083   ///
00084   BOOLEAN    EnableReceiveTimestamps;
00085   ///
00086   /// Set to TRUE to disable background polling in this MNP
00087   /// instance. Note that background polling may not be supported in
00088   /// all MNP implementations. The startup default value is FALSE,
00089   /// unless background polling is not supported.
00090   ///
00091   BOOLEAN    DisableBackgroundPolling;
00092 } EFI_MANAGED_NETWORK_CONFIG_DATA;
00093 
00094 typedef struct {
00095   EFI_TIME      Timestamp;
00096   EFI_EVENT     RecycleEvent;
00097   UINT32        PacketLength;
00098   UINT32        HeaderLength;
00099   UINT32        AddressLength;
00100   UINT32        DataLength;
00101   BOOLEAN       BroadcastFlag;
00102   BOOLEAN       MulticastFlag;
00103   BOOLEAN       PromiscuousFlag;
00104   UINT16        ProtocolType;
00105   VOID          *DestinationAddress;
00106   VOID          *SourceAddress;
00107   VOID          *MediaHeader;
00108   VOID          *PacketData;
00109 } EFI_MANAGED_NETWORK_RECEIVE_DATA;
00110 
00111 typedef struct {
00112   UINT32        FragmentLength;
00113   VOID          *FragmentBuffer;
00114 } EFI_MANAGED_NETWORK_FRAGMENT_DATA;
00115 
00116 typedef struct {
00117   EFI_MAC_ADDRESS                   *DestinationAddress; //OPTIONAL
00118   EFI_MAC_ADDRESS                   *SourceAddress;      //OPTIONAL
00119   UINT16                            ProtocolType;        //OPTIONAL
00120   UINT32                            DataLength;
00121   UINT16                            HeaderLength;        //OPTIONAL
00122   UINT16                            FragmentCount;
00123   EFI_MANAGED_NETWORK_FRAGMENT_DATA FragmentTable[1];
00124 } EFI_MANAGED_NETWORK_TRANSMIT_DATA;
00125 
00126 
00127 typedef struct {
00128   ///
00129   /// This Event will be signaled after the Status field is updated
00130   /// by the MNP. The type of Event must be
00131   /// EFI_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
00132   /// Event must be lower than or equal to TPL_CALLBACK.
00133   ///
00134   EFI_EVENT                             Event;
00135   ///
00136   /// The status that is returned to the caller at the end of the operation
00137   /// to indicate whether this operation completed successfully.
00138   ///
00139   EFI_STATUS                            Status;
00140   union {
00141     ///
00142     /// When this token is used for receiving, RxData is a pointer to the EFI_MANAGED_NETWORK_RECEIVE_DATA.
00143     ///
00144     EFI_MANAGED_NETWORK_RECEIVE_DATA    *RxData;
00145     ///
00146     /// When this token is used for transmitting, TxData is a pointer to the EFI_MANAGED_NETWORK_TRANSMIT_DATA.
00147     ///
00148     EFI_MANAGED_NETWORK_TRANSMIT_DATA   *TxData;
00149   } Packet;
00150 } EFI_MANAGED_NETWORK_COMPLETION_TOKEN;
00151 
00152 /**
00153   Returns the operational parameters for the current MNP child driver.
00154 
00155   @param  This          The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
00156   @param  MnpConfigData The pointer to storage for MNP operational parameters.
00157   @param  SnpModeData   The pointer to storage for SNP operational parameters.
00158 
00159   @retval EFI_SUCCESS           The operation completed successfully.
00160   @retval EFI_INVALID_PARAMETER This is NULL.
00161   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
00162   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured. The default
00163                                 values are returned in MnpConfigData if it is not NULL.
00164   @retval Other                 The mode data could not be read.
00165 
00166 **/
00167 typedef
00168 EFI_STATUS
00169 (EFIAPI *EFI_MANAGED_NETWORK_GET_MODE_DATA)(
00170   IN  EFI_MANAGED_NETWORK_PROTOCOL     *This,
00171   OUT EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL,
00172   OUT EFI_SIMPLE_NETWORK_MODE          *SnpModeData    OPTIONAL
00173   );
00174 
00175 /**
00176   Sets or clears the operational parameters for the MNP child driver.
00177 
00178   @param  This          The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
00179   @param  MnpConfigData The pointer to configuration data that will be assigned to the MNP
00180                         child driver instance. If NULL, the MNP child driver instance is
00181                         reset to startup defaults and all pending transmit and receive
00182                         requests are flushed.
00183 
00184   @retval EFI_SUCCESS           The operation completed successfully.
00185   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
00186   @retval EFI_OUT_OF_RESOURCES  Required system resources (usually memory) could not be
00187                                 allocated.
00188   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this [MNP]
00189                                 implementation.
00190   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
00191   @retval Other                 The MNP child driver instance has been reset to startup defaults.
00192 
00193 **/
00194 typedef
00195 EFI_STATUS
00196 (EFIAPI *EFI_MANAGED_NETWORK_CONFIGURE)(
00197   IN EFI_MANAGED_NETWORK_PROTOCOL     *This,
00198   IN EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL
00199   );
00200 
00201 /**
00202   Translates an IP multicast address to a hardware (MAC) multicast address.
00203 
00204   @param  This       The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
00205   @param  Ipv6Flag   Set to TRUE to if IpAddress is an IPv6 multicast address.
00206                      Set to FALSE if IpAddress is an IPv4 multicast address.
00207   @param  IpAddress  The pointer to the multicast IP address (in network byte order) to convert.
00208   @param  MacAddress The pointer to the resulting multicast MAC address.
00209 
00210   @retval EFI_SUCCESS           The operation completed successfully.
00211   @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:
00212                                 - This is NULL.
00213                                 - IpAddress is NULL.
00214                                 - *IpAddress is not a valid multicast IP address.
00215                                 - MacAddress is NULL.
00216   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
00217   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
00218   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
00219   @retval Other                 The address could not be converted.
00220 
00221 **/
00222 typedef
00223 EFI_STATUS
00224 (EFIAPI *EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC)(
00225   IN  EFI_MANAGED_NETWORK_PROTOCOL  *This,
00226   IN  BOOLEAN                       Ipv6Flag,
00227   IN  EFI_IP_ADDRESS                *IpAddress,
00228   OUT EFI_MAC_ADDRESS               *MacAddress
00229   );
00230 
00231 /**
00232   Enables and disables receive filters for multicast address.
00233 
00234   @param  This       The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
00235   @param  JoinFlag   Set to TRUE to join this multicast group.
00236                      Set to FALSE to leave this multicast group.
00237   @param  MacAddress The pointer to the multicast MAC group (address) to join or leave.
00238 
00239   @retval EFI_SUCCESS           The requested operation completed successfully.
00240   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
00241                                 - This is NULL.
00242                                 - JoinFlag is TRUE and MacAddress is NULL.
00243                                 - *MacAddress is not a valid multicast MAC address.
00244   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
00245   @retval EFI_ALREADY_STARTED   The supplied multicast group is already joined.
00246   @retval EFI_NOT_FOUND         The supplied multicast group is not joined.
00247   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
00248   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
00249   @retval Other                 The requested operation could not be completed.
00250 
00251 **/
00252 typedef
00253 EFI_STATUS
00254 (EFIAPI *EFI_MANAGED_NETWORK_GROUPS)(
00255   IN EFI_MANAGED_NETWORK_PROTOCOL  *This,
00256   IN BOOLEAN                       JoinFlag,
00257   IN EFI_MAC_ADDRESS               *MacAddress  OPTIONAL
00258   );
00259 
00260 /**
00261   Places asynchronous outgoing data packets into the transmit queue.
00262 
00263   @param  This  The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
00264   @param  Token The pointer to a token associated with the transmit data descriptor.
00265 
00266   @retval EFI_SUCCESS           The transmit completion token was cached.
00267   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
00268   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
00269   @retval EFI_ACCESS_DENIED     The transmit completion token is already in the transmit queue.
00270   @retval EFI_OUT_OF_RESOURCES  The transmit data could not be queued due to a lack of system resources
00271                                 (usually memory).
00272   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
00273   @retval EFI_NOT_READY         The transmit request could not be queued because the transmit queue is full.
00274 
00275 **/
00276 typedef
00277 EFI_STATUS
00278 (EFIAPI *EFI_MANAGED_NETWORK_TRANSMIT)(
00279   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
00280   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token
00281   );
00282 
00283 /**
00284   Places an asynchronous receiving request into the receiving queue.
00285 
00286   @param  This  The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
00287   @param  Token The pointer to a token associated with the receive data descriptor.
00288 
00289   @retval EFI_SUCCESS           The receive completion token was cached.
00290   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
00291   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
00292                                 - This is NULL.
00293                                 - Token is NULL.
00294                                 - Token.Event is NULL.
00295   @retval EFI_OUT_OF_RESOURCES  The transmit data could not be queued due to a lack of system resources
00296                                 (usually memory).
00297   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
00298   @retval EFI_ACCESS_DENIED     The receive completion token was already in the receive queue.
00299   @retval EFI_NOT_READY         The receive request could not be queued because the receive queue is full.
00300 
00301 **/
00302 typedef
00303 EFI_STATUS
00304 (EFIAPI *EFI_MANAGED_NETWORK_RECEIVE)(
00305   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
00306   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token
00307   );
00308 
00309 
00310 /**
00311   Aborts an asynchronous transmit or receive request.
00312 
00313   @param  This  The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
00314   @param  Token The pointer to a token that has been issued by
00315                 EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or
00316                 EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If
00317                 NULL, all pending tokens are aborted.
00318 
00319   @retval  EFI_SUCCESS           The asynchronous I/O request was aborted and Token.Event
00320                                  was signaled. When Token is NULL, all pending requests were
00321                                  aborted and their events were signaled.
00322   @retval  EFI_NOT_STARTED       This MNP child driver instance has not been configured.
00323   @retval  EFI_INVALID_PARAMETER This is NULL.
00324   @retval  EFI_NOT_FOUND         When Token is not NULL, the asynchronous I/O request was
00325                                  not found in the transmit or receive queue. It has either completed
00326                                  or was not issued by Transmit() and Receive().
00327 
00328 **/
00329 typedef
00330 EFI_STATUS
00331 (EFIAPI *EFI_MANAGED_NETWORK_CANCEL)(
00332   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
00333   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token  OPTIONAL
00334   );
00335 
00336 /**
00337   Polls for incoming data packets and processes outgoing data packets.
00338 
00339   @param  This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
00340 
00341   @retval EFI_SUCCESS      Incoming or outgoing data was processed.
00342   @retval EFI_NOT_STARTED  This MNP child driver instance has not been configured.
00343   @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
00344   @retval EFI_NOT_READY    No incoming or outgoing data was processed. Consider increasing
00345                            the polling rate.
00346   @retval EFI_TIMEOUT      Data was dropped out of the transmit and/or receive queue.
00347                             Consider increasing the polling rate.
00348 
00349 **/
00350 typedef
00351 EFI_STATUS
00352 (EFIAPI *EFI_MANAGED_NETWORK_POLL)(
00353   IN EFI_MANAGED_NETWORK_PROTOCOL    *This
00354   );
00355 
00356 ///
00357 /// The MNP is used by network applications (and drivers) to
00358 /// perform raw (unformatted) asynchronous network packet I/O.
00359 ///
00360 struct _EFI_MANAGED_NETWORK_PROTOCOL {
00361   EFI_MANAGED_NETWORK_GET_MODE_DATA       GetModeData;
00362   EFI_MANAGED_NETWORK_CONFIGURE           Configure;
00363   EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC     McastIpToMac;
00364   EFI_MANAGED_NETWORK_GROUPS              Groups;
00365   EFI_MANAGED_NETWORK_TRANSMIT            Transmit;
00366   EFI_MANAGED_NETWORK_RECEIVE             Receive;
00367   EFI_MANAGED_NETWORK_CANCEL              Cancel;
00368   EFI_MANAGED_NETWORK_POLL                Poll;
00369 };
00370 
00371 extern EFI_GUID gEfiManagedNetworkServiceBindingProtocolGuid;
00372 extern EFI_GUID gEfiManagedNetworkProtocolGuid;
00373 
00374 #endif