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, 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   Module Name:  ManagedNetwork.h
  15
  16 **/
  17
  18 #ifndef _EFI_MANAGED_NETWORK_PROTOCOL_H
  19 #define _EFI_MANAGED_NETWORK_PROTOCOL_H
  20
  21 #include <Protocol/SimpleNetwork.h>
  22
  23 #define EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL_GUID \
  24   { \
  25     0xf36ff770, 0xa7e1, 0x42cf, {0x9e, 0xd2, 0x56, 0xf0, 0xf2, 0x71, 0xf4, 0x4c } \
  26   }
  27
  28 #define EFI_MANAGED_NETWORK_PROTOCOL_GUID \
  29   { \
  30     0x3b95aa31, 0x3793, 0x434b, {0x86, 0x67, 0xc8, 0x7, 0x8, 0x92, 0xe0, 0x5e } \
  31   }
  32
  33 typedef struct _EFI_MANAGED_NETWORK_PROTOCOL EFI_MANAGED_NETWORK_PROTOCOL;
  34
  35 typedef struct {
  36   UINT32     ReceivedQueueTimeoutValue;
  37   UINT32     TransmitQueueTimeoutValue;
  38   UINT16     ProtocolTypeFilter;
  39   BOOLEAN    EnableUnicastReceive;
  40   BOOLEAN    EnableMulticastReceive;
  41   BOOLEAN    EnableBroadcastReceive;
  42   BOOLEAN    EnablePromiscuousReceive;
  43   BOOLEAN    FlushQueuesOnReset;
  44   BOOLEAN    EnableReceiveTimestamps;
  45   BOOLEAN    DisableBackgroundPolling;
  46 } EFI_MANAGED_NETWORK_CONFIG_DATA;
  47
  48 typedef struct {
  49   EFI_TIME      Timestamp;
  50   EFI_EVENT     RecycleEvent;
  51   UINT32        PacketLength;
  52   UINT32        HeaderLength;
  53   UINT32        AddressLength;
  54   UINT32        DataLength;
  55   BOOLEAN       BroadcastFlag;
  56   BOOLEAN       MulticastFlag;
  57   BOOLEAN       PromiscuousFlag;
  58   UINT16        ProtocolType;
  59   VOID          *DestinationAddress;
  60   VOID          *SourceAddress;
  61   VOID          *MediaHeader;
  62   VOID          *PacketData;
  63 } EFI_MANAGED_NETWORK_RECEIVE_DATA;
  64
  65 typedef struct {
  66   UINT32        FragmentLength;
  67   VOID          *FragmentBuffer;
  68 } EFI_MANAGED_NETWORK_FRAGMENT_DATA;
  69
  70 typedef struct {
  71   EFI_MAC_ADDRESS                   *DestinationAddress; //OPTIONAL
  72   EFI_MAC_ADDRESS                   *SourceAddress;      //OPTIONAL
  73   UINT16                            ProtocolType;        //OPTIONAL
  74   UINT32                            DataLength;
  75   UINT16                            HeaderLength;        //OPTIONAL
  76   UINT16                            FragmentCount;
  77   EFI_MANAGED_NETWORK_FRAGMENT_DATA FragmentTable[1];
  78 } EFI_MANAGED_NETWORK_TRANSMIT_DATA;
  79
  80
  81 typedef struct {
  82   EFI_EVENT                             Event;
  83   EFI_STATUS                            Status;
  84   union {
  85     EFI_MANAGED_NETWORK_RECEIVE_DATA    *RxData;
  86     EFI_MANAGED_NETWORK_TRANSMIT_DATA   *TxData;
  87   } Packet;
  88 } EFI_MANAGED_NETWORK_COMPLETION_TOKEN;
  89
  90 /**
  91   Returns the operational parameters for the current MNP child driver.
  92
  93   @param  This          Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
  94   @param  MnpConfigData Pointer to storage for MNP operational parameters.
  95   @param  SnpModeData   Pointer to storage for SNP operational parameters.
  96
  97   @retval EFI_SUCCESS           The operation completed successfully.
  98   @retval EFI_INVALID_PARAMETER This is NULL.
  99   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
 100   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured. The default
 101                                 values are returned in MnpConfigData if it is not NULL.
 102   @retval Other                 The mode data could not be read.
 103
 104 **/
 105 typedef
 106 EFI_STATUS
 107 (EFIAPI *EFI_MANAGED_NETWORK_GET_MODE_DATA) (
 108   IN  EFI_MANAGED_NETWORK_PROTOCOL     *This,
 109   OUT EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL,
 110   OUT EFI_SIMPLE_NETWORK_MODE          *SnpModeData    OPTIONAL
 111   )
 112 ;
 113
 114 /**
 115   Sets or clears the operational parameters for the MNP child driver.
 116
 117   @param  This          Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 118   @param  MnpConfigData Pointer to configuration data that will be assigned to the MNP
 119                         child driver instance. If NULL, the MNP child driver instance is
 120                         reset to startup defaults and all pending transmit and receive
 121                         requests are flushed.
 122
 123   @retval EFI_SUCCESS           The operation completed successfully.
 124   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 125   @retval EFI_OUT_OF_RESOURCES  Required system resources (usually memory) could not be
 126                                 allocated.
 127   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this [MNP]
 128                                 implementation.
 129   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 130   @retval Other                 The MNP child driver instance has been reset to startup defaults.
 131
 132 **/
 133 typedef
 134 EFI_STATUS
 135 (EFIAPI *EFI_MANAGED_NETWORK_CONFIGURE) (
 136   IN EFI_MANAGED_NETWORK_PROTOCOL     *This,
 137   IN EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL
 138   )
 139 ;
 140
 141 /**
 142   Translates an IP multicast address to a hardware (MAC) multicast address.
 143
 144   @param  This       Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 145   @param  Ipv6Flag   Set to TRUE to if IpAddress is an IPv6 multicast address.
 146                      Set to FALSE if IpAddress is an IPv4 multicast address.
 147   @param  IpAddress  Pointer to the multicast IP address (in network byte order) to convert.
 148   @param  MacAddress Pointer to the resulting multicast MAC address.
 149
 150   @retval EFI_SUCCESS           The operation completed successfully.
 151   @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:
 152                                 - This is NULL.
 153                                 - IpAddress is NULL.
 154                                 - *IpAddress is not a valid multicast IP address.
 155                                 - MacAddress is NULL.
 156   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
 157   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
 158   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 159   @retval Other                 The address could not be converted.
 160
 161 **/
 162 typedef
 163 EFI_STATUS
 164 (EFIAPI *EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC) (
 165   IN  EFI_MANAGED_NETWORK_PROTOCOL  *This,
 166   IN  BOOLEAN                       Ipv6Flag,
 167   IN  EFI_IP_ADDRESS                *IpAddress,
 168   OUT EFI_MAC_ADDRESS               *MacAddress
 169   )
 170 ;
 171
 172 /**
 173   Enables and disables receive filters for multicast address.
 174
 175   @param  This       Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 176   @param  JoinFlag   Set to TRUE to join this multicast group.
 177                      Set to FALSE to leave this multicast group.
 178   @param  MacAddress Pointer to the multicast MAC group (address) to join or leave.
 179
 180   @retval EFI_SUCCESS           The requested operation completed successfully.
 181   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 182                                 - This is NULL.
 183                                 - JoinFlag is TRUE and MacAddress is NULL.
 184                                 - *MacAddress is not a valid multicast MAC address.
 185   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
 186   @retval EFI_ALREADY_STARTED   The supplied multicast group is already joined.
 187   @retval EFI_NOT_FOUND         The supplied multicast group is not joined.
 188   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 189   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
 190   @retval Other                 The requested operation could not be completed.
 191
 192 **/
 193 typedef
 194 EFI_STATUS
 195 (EFIAPI *EFI_MANAGED_NETWORK_GROUPS) (
 196   IN EFI_MANAGED_NETWORK_PROTOCOL  *This,
 197   IN BOOLEAN                       JoinFlag,
 198   IN EFI_MAC_ADDRESS               *MacAddress  OPTIONAL
 199   )
 200 ;
 201
 202 /**
 203   Places asynchronous outgoing data packets into the transmit queue.
 204
 205   @param  This  Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 206   @param  Token Pointer to a token associated with the transmit data descriptor.
 207
 208   @retval EFI_SUCCESS           The transmit completion token was cached.
 209   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
 210   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 211   @retval EFI_ACCESS_DENIED     The transmit completion token is already in the transmit queue.
 212   @retval EFI_OUT_OF_RESOURCES  The transmit data could not be queued due to a lack of system resources
 213                                 (usually memory).
 214   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 215   @retval EFI_NOT_READY         The transmit request could not be queued because the transmit queue is full.
 216
 217 **/
 218 typedef
 219 EFI_STATUS
 220 (EFIAPI *EFI_MANAGED_NETWORK_TRANSMIT) (
 221   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
 222   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token
 223   )
 224 ;
 225
 226 /**
 227   Places an asynchronous receiving request into the receiving queue.
 228
 229   @param  This  Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 230   @param  Token Pointer to a token associated with the receive data descriptor.
 231
 232   @retval EFI_SUCCESS           The receive completion token was cached.
 233   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
 234   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 235                                 - This is NULL.
 236                                 - Token is NULL.
 237                                 - Token.Event is NULL
 238   @retval EFI_OUT_OF_RESOURCES  The transmit data could not be queued due to a lack of system resources
 239                                 (usually memory).
 240   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 241   @retval EFI_ACCESS_DENIED     The receive completion token was already in the receive queue.
 242   @retval EFI_NOT_READY         The receive request could not be queued because the receive queue is full.
 243
 244 **/
 245 typedef
 246 EFI_STATUS
 247 (EFIAPI *EFI_MANAGED_NETWORK_RECEIVE) (
 248   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
 249   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token
 250   )
 251 ;
 252
 253
 254 /**
 255   Aborts an asynchronous transmit or receive request.
 256
 257   @param  This  Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 258   @param  Token Pointer to a token that has been issued by
 259                 EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or
 260                 EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If
 261                 NULL, all pending tokens are aborted.
 262
 263   @retval  EFI_SUCCESS           The asynchronous I/O request was aborted and Token.Event
 264                                  was signaled. When Token is NULL, all pending requests were
 265                                  aborted and their events were signaled.
 266   @retval  EFI_NOT_STARTED       This MNP child driver instance has not been configured.
 267   @retval  EFI_INVALID_PARAMETER This is NULL.
 268   @retval  EFI_NOT_FOUND         When Token is not NULL, the asynchronous I/O request was
 269                                  not found in the transmit or receive queue. It has either completed
 270                                  or was not issued by Transmit() and Receive().
 271
 272 **/
 273 typedef
 274 EFI_STATUS
 275 (EFIAPI *EFI_MANAGED_NETWORK_CANCEL) (
 276   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
 277   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token  OPTIONAL
 278   )
 279 ;
 280
 281 /**
 282   Polls for incoming data packets and processes outgoing data packets.
 283
 284   @param  This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 285
 286   @retval EFI_SUCCESS      Incoming or outgoing data was processed.
 287   @retval EFI_NOT_STARTED  This MNP child driver instance has not been configured.
 288   @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
 289   @retval EFI_NOT_READY    No incoming or outgoing data was processed. Consider increasing
 290                            the polling rate.
 291   @retval EFI_TIMEOUT      Data was dropped out of the transmit and/or receive queue.
 292                             Consider increasing the polling rate.
 293
 294 **/
 295 typedef
 296 EFI_STATUS
 297 (EFIAPI *EFI_MANAGED_NETWORK_POLL) (
 298   IN EFI_MANAGED_NETWORK_PROTOCOL    *This
 299   )
 300 ;
 301
 302 struct _EFI_MANAGED_NETWORK_PROTOCOL {
 303   EFI_MANAGED_NETWORK_GET_MODE_DATA       GetModeData;
 304   EFI_MANAGED_NETWORK_CONFIGURE           Configure;
 305   EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC     McastIpToMac;
 306   EFI_MANAGED_NETWORK_GROUPS              Groups;
 307   EFI_MANAGED_NETWORK_TRANSMIT            Transmit;
 308   EFI_MANAGED_NETWORK_RECEIVE             Receive;
 309   EFI_MANAGED_NETWORK_CANCEL              Cancel;
 310   EFI_MANAGED_NETWORK_POLL                Poll;
 311 };
 312
 313 extern EFI_GUID gEfiManagedNetworkServiceBindingProtocolGuid;
 314 extern EFI_GUID gEfiManagedNetworkProtocolGuid;
 315
 316 #endif