MdePkg/Include/Protocol/ManagedNetwork.h

   1 /** @file
   2   EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL as defined in UEFI 2.0.
   3   EFI_MANAGED_NETWORK_PROTOCOL as defined in UEFI 2.0.
   4
   5   Copyright (c) 2006 - 2008, Intel Corporation
   6   All rights reserved. This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef __EFI_MANAGED_NETWORK_PROTOCOL_H__
  17 #define __EFI_MANAGED_NETWORK_PROTOCOL_H__
  18
  19 #include <Protocol/SimpleNetwork.h>
  20
  21 #define EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL_GUID \
  22   { \
  23     0xf36ff770, 0xa7e1, 0x42cf, {0x9e, 0xd2, 0x56, 0xf0, 0xf2, 0x71, 0xf4, 0x4c } \
  24   }
  25
  26 #define EFI_MANAGED_NETWORK_PROTOCOL_GUID \
  27   { \
  28     0x7ab33a91, 0xace5, 0x4326, { 0xb5, 0x72, 0xe7, 0xee, 0x33, 0xd3, 0x9f, 0x16 } \
  29   }
  30
  31 typedef struct _EFI_MANAGED_NETWORK_PROTOCOL EFI_MANAGED_NETWORK_PROTOCOL;
  32
  33 typedef struct {
  34   ///
  35   /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed
  36   /// from the MNP receive queue will be dropped if its receive timeout expires.
  37   ///
  38   UINT32     ReceivedQueueTimeoutValue;
  39   ///
  40   /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed
  41   /// from the MNP transmit queue will be dropped if its receive timeout expires.
  42   ///
  43   UINT32     TransmitQueueTimeoutValue;
  44   ///
  45   /// Ethernet type II 16-bit protocol type in host byte order. Valid
  46   /// values are zero and 1,500 to 65,535.
  47   ///
  48   UINT16     ProtocolTypeFilter;
  49   ///
  50   /// Set to TRUE to receive packets that are sent to the network
  51   /// device MAC address. The startup default value is FALSE.
  52   ///
  53   BOOLEAN    EnableUnicastReceive;
  54   ///
  55   /// Set to TRUE to receive packets that are sent to any of the
  56   /// active multicast groups. The startup default value is FALSE.
  57   ///
  58   BOOLEAN    EnableMulticastReceive;
  59   ///
  60   /// Set to TRUE to receive packets that are sent to the network
  61   /// device broadcast address. The startup default value is FALSE.
  62   ///
  63   BOOLEAN    EnableBroadcastReceive;
  64   ///
  65   /// Set to TRUE to receive packets that are sent to any MAC address.
  66   /// The startup default value is FALSE.
  67   ///
  68   BOOLEAN    EnablePromiscuousReceive;
  69   ///
  70   /// Set to TRUE to drop queued packets when the configuration
  71   /// is changed. The startup default value is FALSE.
  72   ///
  73   BOOLEAN    FlushQueuesOnReset;
  74   ///
  75   /// Set to TRUE to timestamp all packets when they are received
  76   /// by the MNP. Note that timestamps may be unsupported in some
  77   /// MNP implementations. The startup default value is FALSE.
  78   ///
  79   BOOLEAN    EnableReceiveTimestamps;
  80   ///
  81   /// Set to TRUE to disable background polling in this MNP
  82   /// instance. Note that background polling may not be supported in
  83   /// all MNP implementations. The startup default value is FALSE,
  84   /// unless background polling is not supported.
  85   ///
  86   BOOLEAN    DisableBackgroundPolling;
  87 } EFI_MANAGED_NETWORK_CONFIG_DATA;
  88
  89 typedef struct {
  90   EFI_TIME      Timestamp;
  91   EFI_EVENT     RecycleEvent;
  92   UINT32        PacketLength;
  93   UINT32        HeaderLength;
  94   UINT32        AddressLength;
  95   UINT32        DataLength;
  96   BOOLEAN       BroadcastFlag;
  97   BOOLEAN       MulticastFlag;
  98   BOOLEAN       PromiscuousFlag;
  99   UINT16        ProtocolType;
 100   VOID          *DestinationAddress;
 101   VOID          *SourceAddress;
 102   VOID          *MediaHeader;
 103   VOID          *PacketData;
 104 } EFI_MANAGED_NETWORK_RECEIVE_DATA;
 105
 106 typedef struct {
 107   UINT32        FragmentLength;
 108   VOID          *FragmentBuffer;
 109 } EFI_MANAGED_NETWORK_FRAGMENT_DATA;
 110
 111 typedef struct {
 112   EFI_MAC_ADDRESS                   *DestinationAddress; //OPTIONAL
 113   EFI_MAC_ADDRESS                   *SourceAddress;      //OPTIONAL
 114   UINT16                            ProtocolType;        //OPTIONAL
 115   UINT32                            DataLength;
 116   UINT16                            HeaderLength;        //OPTIONAL
 117   UINT16                            FragmentCount;
 118   EFI_MANAGED_NETWORK_FRAGMENT_DATA FragmentTable[1];
 119 } EFI_MANAGED_NETWORK_TRANSMIT_DATA;
 120
 121
 122 typedef struct {
 123   ///
 124   /// This Event will be signaled after the Status field is updated
 125   /// by the MNP. The type of Event must be
 126   /// EFI_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
 127   /// Event must be lower than or equal to TPL_CALLBACK.
 128   ///
 129   EFI_EVENT                             Event;
 130   ///
 131   /// The status that is returned to the caller at the end of the operation
 132   /// to indicate whether this operation completed successfully.
 133   ///
 134   EFI_STATUS                            Status;
 135   union {
 136     ///
 137     /// When this token is used for receiving, RxData is a pointer to the EFI_MANAGED_NETWORK_RECEIVE_DATA.
 138     ///
 139     EFI_MANAGED_NETWORK_RECEIVE_DATA    *RxData;
 140     ///
 141     /// When this token is used for transmitting, TxData is a pointer to the EFI_MANAGED_NETWORK_TRANSMIT_DATA.
 142     ///
 143     EFI_MANAGED_NETWORK_TRANSMIT_DATA   *TxData;
 144   } Packet;
 145 } EFI_MANAGED_NETWORK_COMPLETION_TOKEN;
 146
 147 /**
 148   Returns the operational parameters for the current MNP child driver.
 149
 150   @param  This          Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 151   @param  MnpConfigData Pointer to storage for MNP operational parameters.
 152   @param  SnpModeData   Pointer to storage for SNP operational parameters.
 153
 154   @retval EFI_SUCCESS           The operation completed successfully.
 155   @retval EFI_INVALID_PARAMETER This is NULL.
 156   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
 157   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured. The default
 158                                 values are returned in MnpConfigData if it is not NULL.
 159   @retval Other                 The mode data could not be read.
 160
 161 **/
 162 typedef
 163 EFI_STATUS
 164 (EFIAPI *EFI_MANAGED_NETWORK_GET_MODE_DATA)(
 165   IN  EFI_MANAGED_NETWORK_PROTOCOL     *This,
 166   OUT EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL,
 167   OUT EFI_SIMPLE_NETWORK_MODE          *SnpModeData    OPTIONAL
 168   );
 169
 170 /**
 171   Sets or clears the operational parameters for the MNP child driver.
 172
 173   @param  This          Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 174   @param  MnpConfigData Pointer to configuration data that will be assigned to the MNP
 175                         child driver instance. If NULL, the MNP child driver instance is
 176                         reset to startup defaults and all pending transmit and receive
 177                         requests are flushed.
 178
 179   @retval EFI_SUCCESS           The operation completed successfully.
 180   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 181   @retval EFI_OUT_OF_RESOURCES  Required system resources (usually memory) could not be
 182                                 allocated.
 183   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this [MNP]
 184                                 implementation.
 185   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 186   @retval Other                 The MNP child driver instance has been reset to startup defaults.
 187
 188 **/
 189 typedef
 190 EFI_STATUS
 191 (EFIAPI *EFI_MANAGED_NETWORK_CONFIGURE)(
 192   IN EFI_MANAGED_NETWORK_PROTOCOL     *This,
 193   IN EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL
 194   );
 195
 196 /**
 197   Translates an IP multicast address to a hardware (MAC) multicast address.
 198
 199   @param  This       Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 200   @param  Ipv6Flag   Set to TRUE to if IpAddress is an IPv6 multicast address.
 201                      Set to FALSE if IpAddress is an IPv4 multicast address.
 202   @param  IpAddress  Pointer to the multicast IP address (in network byte order) to convert.
 203   @param  MacAddress Pointer to the resulting multicast MAC address.
 204
 205   @retval EFI_SUCCESS           The operation completed successfully.
 206   @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:
 207                                 - This is NULL.
 208                                 - IpAddress is NULL.
 209                                 - *IpAddress is not a valid multicast IP address.
 210                                 - MacAddress is NULL.
 211   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
 212   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
 213   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 214   @retval Other                 The address could not be converted.
 215
 216 **/
 217 typedef
 218 EFI_STATUS
 219 (EFIAPI *EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC)(
 220   IN  EFI_MANAGED_NETWORK_PROTOCOL  *This,
 221   IN  BOOLEAN                       Ipv6Flag,
 222   IN  EFI_IP_ADDRESS                *IpAddress,
 223   OUT EFI_MAC_ADDRESS               *MacAddress
 224   );
 225
 226 /**
 227   Enables and disables receive filters for multicast address.
 228
 229   @param  This       Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 230   @param  JoinFlag   Set to TRUE to join this multicast group.
 231                      Set to FALSE to leave this multicast group.
 232   @param  MacAddress Pointer to the multicast MAC group (address) to join or leave.
 233
 234   @retval EFI_SUCCESS           The requested operation completed successfully.
 235   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 236                                 - This is NULL.
 237                                 - JoinFlag is TRUE and MacAddress is NULL.
 238                                 - *MacAddress is not a valid multicast MAC address.
 239   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
 240   @retval EFI_ALREADY_STARTED   The supplied multicast group is already joined.
 241   @retval EFI_NOT_FOUND         The supplied multicast group is not joined.
 242   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 243   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
 244   @retval Other                 The requested operation could not be completed.
 245
 246 **/
 247 typedef
 248 EFI_STATUS
 249 (EFIAPI *EFI_MANAGED_NETWORK_GROUPS)(
 250   IN EFI_MANAGED_NETWORK_PROTOCOL  *This,
 251   IN BOOLEAN                       JoinFlag,
 252   IN EFI_MAC_ADDRESS               *MacAddress  OPTIONAL
 253   );
 254
 255 /**
 256   Places asynchronous outgoing data packets into the transmit queue.
 257
 258   @param  This  Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 259   @param  Token Pointer to a token associated with the transmit data descriptor.
 260
 261   @retval EFI_SUCCESS           The transmit completion token was cached.
 262   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
 263   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 264   @retval EFI_ACCESS_DENIED     The transmit completion token is already in the transmit queue.
 265   @retval EFI_OUT_OF_RESOURCES  The transmit data could not be queued due to a lack of system resources
 266                                 (usually memory).
 267   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 268   @retval EFI_NOT_READY         The transmit request could not be queued because the transmit queue is full.
 269
 270 **/
 271 typedef
 272 EFI_STATUS
 273 (EFIAPI *EFI_MANAGED_NETWORK_TRANSMIT)(
 274   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
 275   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token
 276   );
 277
 278 /**
 279   Places an asynchronous receiving request into the receiving queue.
 280
 281   @param  This  Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 282   @param  Token Pointer to a token associated with the receive data descriptor.
 283
 284   @retval EFI_SUCCESS           The receive completion token was cached.
 285   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
 286   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 287                                 - This is NULL.
 288                                 - Token is NULL.
 289                                 - Token.Event is NULL
 290   @retval EFI_OUT_OF_RESOURCES  The transmit data could not be queued due to a lack of system resources
 291                                 (usually memory).
 292   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 293   @retval EFI_ACCESS_DENIED     The receive completion token was already in the receive queue.
 294   @retval EFI_NOT_READY         The receive request could not be queued because the receive queue is full.
 295
 296 **/
 297 typedef
 298 EFI_STATUS
 299 (EFIAPI *EFI_MANAGED_NETWORK_RECEIVE)(
 300   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
 301   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token
 302   );
 303
 304
 305 /**
 306   Aborts an asynchronous transmit or receive request.
 307
 308   @param  This  Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 309   @param  Token Pointer to a token that has been issued by
 310                 EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or
 311                 EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If
 312                 NULL, all pending tokens are aborted.
 313
 314   @retval  EFI_SUCCESS           The asynchronous I/O request was aborted and Token.Event
 315                                  was signaled. When Token is NULL, all pending requests were
 316                                  aborted and their events were signaled.
 317   @retval  EFI_NOT_STARTED       This MNP child driver instance has not been configured.
 318   @retval  EFI_INVALID_PARAMETER This is NULL.
 319   @retval  EFI_NOT_FOUND         When Token is not NULL, the asynchronous I/O request was
 320                                  not found in the transmit or receive queue. It has either completed
 321                                  or was not issued by Transmit() and Receive().
 322
 323 **/
 324 typedef
 325 EFI_STATUS
 326 (EFIAPI *EFI_MANAGED_NETWORK_CANCEL)(
 327   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
 328   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token  OPTIONAL
 329   );
 330
 331 /**
 332   Polls for incoming data packets and processes outgoing data packets.
 333
 334   @param  This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 335
 336   @retval EFI_SUCCESS      Incoming or outgoing data was processed.
 337   @retval EFI_NOT_STARTED  This MNP child driver instance has not been configured.
 338   @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
 339   @retval EFI_NOT_READY    No incoming or outgoing data was processed. Consider increasing
 340                            the polling rate.
 341   @retval EFI_TIMEOUT      Data was dropped out of the transmit and/or receive queue.
 342                             Consider increasing the polling rate.
 343
 344 **/
 345 typedef
 346 EFI_STATUS
 347 (EFIAPI *EFI_MANAGED_NETWORK_POLL)(
 348   IN EFI_MANAGED_NETWORK_PROTOCOL    *This
 349   );
 350
 351 ///
 352 /// The MNP is used by network applications (and drivers) to
 353 /// perform raw (unformatted) asynchronous network packet I/O.
 354 ///
 355 struct _EFI_MANAGED_NETWORK_PROTOCOL {
 356   EFI_MANAGED_NETWORK_GET_MODE_DATA       GetModeData;
 357   EFI_MANAGED_NETWORK_CONFIGURE           Configure;
 358   EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC     McastIpToMac;
 359   EFI_MANAGED_NETWORK_GROUPS              Groups;
 360   EFI_MANAGED_NETWORK_TRANSMIT            Transmit;
 361   EFI_MANAGED_NETWORK_RECEIVE             Receive;
 362   EFI_MANAGED_NETWORK_CANCEL              Cancel;
 363   EFI_MANAGED_NETWORK_POLL                Poll;
 364 };
 365
 366 extern EFI_GUID gEfiManagedNetworkServiceBindingProtocolGuid;
 367 extern EFI_GUID gEfiManagedNetworkProtocolGuid;
 368
 369 #endif