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