NetworkPkg/Ip4Dxe/Ip4If.h

   1 /** @file
   2   Definition for IP4 pseudo interface structure.
   3
   4 Copyright (c) 2005 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __EFI_IP4_IF_H__
  10 #define __EFI_IP4_IF_H__
  11
  12 #define IP4_FRAME_RX_SIGNATURE   SIGNATURE_32 ('I', 'P', 'F', 'R')
  13 #define IP4_FRAME_TX_SIGNATURE   SIGNATURE_32 ('I', 'P', 'F', 'T')
  14 #define IP4_FRAME_ARP_SIGNATURE  SIGNATURE_32 ('I', 'P', 'F', 'A')
  15 #define IP4_INTERFACE_SIGNATURE  SIGNATURE_32 ('I', 'P', 'I', 'F')
  16
  17 /**
  18   This prototype is used by both receive and transmission.
  19   When receiving Netbuf is allocated by IP4_INTERFACE, and
  20   released by IP4. Flag shows whether the frame is received
  21   as link broadcast/multicast...
  22
  23   When transmitting, the Netbuf is from IP4, and provided
  24   to the callback as a reference. Flag isn't used.
  25
  26   @param[in] IpInstance The instance that sent or received the packet.
  27                         IpInstance can be NULL which means that it is the IP4 driver
  28                         itself sending the packets. IP4 driver may send packets that
  29                         don't belong to any instance, such as ICMP errors, ICMP echo
  30                         responses, or IGMP packets. IpInstance is used as a tag in
  31                         this module.
  32   @param[in] Packet     The sent or received packet.
  33   @param[in] IoStatus   Status of sending or receiving.
  34   @param[in] LinkFlag   Indicate if the frame is received as link broadcast/multicast.
  35                         When transmitting, it is not used.
  36   @param[in] Context    Additional data for callback.
  37
  38   @retval None.
  39 **/
  40 typedef
  41 VOID
  42 (*IP4_FRAME_CALLBACK)(
  43   IN IP4_PROTOCOL  *IpInstance       OPTIONAL,
  44   IN NET_BUF       *Packet,
  45   IN EFI_STATUS    IoStatus,
  46   IN UINT32        LinkFlag,
  47   IN VOID          *Context
  48   );
  49
  50 ///
  51 /// Each receive request is wrapped in an IP4_LINK_RX_TOKEN.
  52 /// Upon completion, the Callback will be called. Only one
  53 /// receive request is send to MNP. IpInstance is always NULL.
  54 /// Reference MNP's spec for information.
  55 ///
  56 typedef struct {
  57   UINT32                                  Signature;
  58   IP4_INTERFACE                           *Interface;
  59
  60   IP4_PROTOCOL                            *IpInstance;
  61   IP4_FRAME_CALLBACK                      CallBack;
  62   VOID                                    *Context;
  63
  64   EFI_MANAGED_NETWORK_COMPLETION_TOKEN    MnpToken;
  65 } IP4_LINK_RX_TOKEN;
  66
  67 ///
  68 /// Each transmit request is wrapped in an IP4_LINK_TX_TOKEN.
  69 /// Upon completion, the Callback will be called.
  70 ///
  71 typedef struct {
  72   UINT32                                  Signature;
  73   LIST_ENTRY                              Link;
  74
  75   IP4_INTERFACE                           *Interface;
  76   IP4_SERVICE                             *IpSb;
  77
  78   IP4_PROTOCOL                            *IpInstance;
  79   IP4_FRAME_CALLBACK                      CallBack;
  80   NET_BUF                                 *Packet;
  81   VOID                                    *Context;
  82
  83   EFI_MAC_ADDRESS                         DstMac;
  84   EFI_MAC_ADDRESS                         SrcMac;
  85
  86   EFI_MANAGED_NETWORK_COMPLETION_TOKEN    MnpToken;
  87   EFI_MANAGED_NETWORK_TRANSMIT_DATA       MnpTxData;
  88 } IP4_LINK_TX_TOKEN;
  89
  90 ///
  91 /// Only one ARP request is requested for all the frames in
  92 /// a time. It is started for the first frames to the Ip. Any
  93 /// subsequent transmission frame will be linked to Frames, and
  94 /// be sent all at once the ARP requests succeed.
  95 ///
  96 typedef struct {
  97   UINT32             Signature;
  98   LIST_ENTRY         Link;
  99
 100   LIST_ENTRY         Frames;
 101   IP4_INTERFACE      *Interface;
 102
 103   //
 104   // ARP requesting staffs
 105   //
 106   EFI_EVENT          OnResolved;
 107   IP4_ADDR           Ip;
 108   EFI_MAC_ADDRESS    Mac;
 109 } IP4_ARP_QUE;
 110
 111 /**
 112   Callback to select which frame to cancel. Caller can cancel a
 113   single frame, or all the frame from an IP instance.
 114
 115   @param Frame      The sending frame to check for cancellation.
 116   @param Context    Additional data for callback.
 117
 118   @retval TRUE      The sending of the frame should be cancelled.
 119   @retval FALSE     Do not cancel the frame sending.
 120 **/
 121 typedef
 122 BOOLEAN
 123 (*IP4_FRAME_TO_CANCEL)(
 124   IP4_LINK_TX_TOKEN  *Frame,
 125   VOID               *Context
 126   );
 127
 128 //
 129 // Each IP4 instance has its own station address. All the instances
 130 // with the same station address share a single interface structure.
 131 // Each interface has its own ARP child, and shares one MNP child.
 132 // Notice the special cases that DHCP can configure the interface
 133 // with 0.0.0.0/0.0.0.0.
 134 //
 135 struct _IP4_INTERFACE {
 136   UINT32                          Signature;
 137   LIST_ENTRY                      Link;
 138   INTN                            RefCnt;
 139
 140   //
 141   // IP address and subnet mask of the interface. It also contains
 142   // the subnet/net broadcast address for quick access. The fields
 143   // are invalid if (Configured == FALSE)
 144   //
 145   IP4_ADDR                        Ip;
 146   IP4_ADDR                        SubnetMask;
 147   IP4_ADDR                        SubnetBrdcast;
 148   IP4_ADDR                        NetBrdcast;
 149   BOOLEAN                         Configured;
 150
 151   //
 152   // Handle used to create/destroy ARP child. All the IP children
 153   // share one MNP which is owned by IP service binding.
 154   //
 155   EFI_HANDLE                      Controller;
 156   EFI_HANDLE                      Image;
 157
 158   EFI_MANAGED_NETWORK_PROTOCOL    *Mnp;
 159   EFI_ARP_PROTOCOL                *Arp;
 160   EFI_HANDLE                      ArpHandle;
 161
 162   //
 163   // Queues to keep the frames sent and waiting ARP request.
 164   //
 165   LIST_ENTRY                      ArpQues;
 166   LIST_ENTRY                      SentFrames;
 167   IP4_LINK_RX_TOKEN               *RecvRequest;
 168
 169   //
 170   // The interface's MAC and broadcast MAC address.
 171   //
 172   EFI_MAC_ADDRESS                 Mac;
 173   EFI_MAC_ADDRESS                 BroadcastMac;
 174   UINT32                          HwaddrLen;
 175
 176   //
 177   // All the IP instances that have the same IP/SubnetMask are linked
 178   // together through IpInstances. If any of the instance enables
 179   // promiscuous receive, PromiscRecv is true.
 180   //
 181   LIST_ENTRY                      IpInstances;
 182   BOOLEAN                         PromiscRecv;
 183 };
 184
 185 /**
 186   Create an IP4_INTERFACE. Delay the creation of ARP instance until
 187   the interface is configured.
 188
 189   @param[in]  Mnp               The shared MNP child of this IP4 service binding
 190                                 instance.
 191   @param[in]  Controller        The controller this IP4 service binding instance
 192                                 is installed. Most like the UNDI handle.
 193   @param[in]  ImageHandle       This driver's image handle.
 194
 195   @return Point to the created IP4_INTERFACE, otherwise NULL.
 196
 197 **/
 198 IP4_INTERFACE *
 199 Ip4CreateInterface (
 200   IN  EFI_MANAGED_NETWORK_PROTOCOL  *Mnp,
 201   IN  EFI_HANDLE                    Controller,
 202   IN  EFI_HANDLE                    ImageHandle
 203   );
 204
 205 /**
 206   Set the interface's address, create and configure
 207   the ARP child if necessary.
 208
 209   @param  Interface         The interface to set the address.
 210   @param  IpAddr            The interface's IP address.
 211   @param  SubnetMask        The interface's netmask.
 212
 213   @retval EFI_SUCCESS           The interface is configured with Ip/netmask pair,
 214                                 and a ARP is created for it.
 215   @retval Others                Failed to set the interface's address.
 216
 217 **/
 218 EFI_STATUS
 219 Ip4SetAddress (
 220   IN OUT IP4_INTERFACE  *Interface,
 221   IN     IP4_ADDR       IpAddr,
 222   IN     IP4_ADDR       SubnetMask
 223   );
 224
 225 /**
 226   Free the interface used by IpInstance. All the IP instance with
 227   the same Ip/Netmask pair share the same interface. It is reference
 228   counted. All the frames haven't been sent will be cancelled.
 229   Because the IpInstance is optional, the caller must remove
 230   IpInstance from the interface's instance list itself.
 231
 232   @param[in]  Interface         The interface used by the IpInstance.
 233   @param[in]  IpInstance        The Ip instance that free the interface. NULL if
 234                                 the Ip driver is releasing the default interface.
 235
 236   @retval EFI_SUCCESS           The interface use IpInstance is freed.
 237
 238 **/
 239 EFI_STATUS
 240 Ip4FreeInterface (
 241   IN  IP4_INTERFACE  *Interface,
 242   IN  IP4_PROTOCOL   *IpInstance           OPTIONAL
 243   );
 244
 245 /**
 246   Send a frame from the interface. If the next hop is broadcast or
 247   multicast address, it is transmitted immediately. If the next hop
 248   is a unicast, it will consult ARP to resolve the NextHop's MAC.
 249   If some error happened, the CallBack won't be called. So, the caller
 250   must test the return value, and take action when there is an error.
 251
 252   @param[in]  Interface         The interface to send the frame from
 253   @param[in]  IpInstance        The IP child that request the transmission.  NULL
 254                                 if it is the IP4 driver itself.
 255   @param[in]  Packet            The packet to transmit.
 256   @param[in]  NextHop           The immediate destination to transmit the packet
 257                                 to.
 258   @param[in]  CallBack          Function to call back when transmit finished.
 259   @param[in]  Context           Opaque parameter to the call back.
 260   @param[in]  IpSb              The pointer to the IP4 service binding instance.
 261
 262   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource to send the frame
 263   @retval EFI_NO_MAPPING        Can't resolve the MAC for the nexthop
 264   @retval EFI_SUCCESS           The packet is successfully transmitted.
 265   @retval other                 Other error occurs.
 266
 267 **/
 268 EFI_STATUS
 269 Ip4SendFrame (
 270   IN  IP4_INTERFACE       *Interface,
 271   IN  IP4_PROTOCOL        *IpInstance       OPTIONAL,
 272   IN  NET_BUF             *Packet,
 273   IN  IP4_ADDR            NextHop,
 274   IN  IP4_FRAME_CALLBACK  CallBack,
 275   IN  VOID                *Context,
 276   IN IP4_SERVICE          *IpSb
 277   );
 278
 279 /**
 280   Remove all the frames on the interface that pass the FrameToCancel,
 281   either queued on ARP queues or that have already been delivered to
 282   MNP and not yet recycled.
 283
 284   @param[in]  Interface         Interface to remove the frames from.
 285   @param[in]  IoStatus          The transmit status returned to the frames'
 286                                 callback.
 287   @param[in]  FrameToCancel     Function to select the frame to cancel, NULL to
 288                                 select all.
 289   @param[in]  Context           Opaque parameters passed to FrameToCancel.
 290
 291 **/
 292 VOID
 293 Ip4CancelFrames (
 294   IN IP4_INTERFACE        *Interface,
 295   IN EFI_STATUS           IoStatus,
 296   IN IP4_FRAME_TO_CANCEL  FrameToCancel    OPTIONAL,
 297   IN VOID                 *Context
 298   );
 299
 300 /**
 301   If there is a pending receive request, cancel it. Don't call
 302   the receive request's callback because this function can be only
 303   called if the instance or driver is tearing itself down. It
 304   doesn't make sense to call it back. But it is necessary to call
 305   the transmit token's callback to give it a chance to free the
 306   packet and update the upper layer's transmit request status, say
 307   that from the UDP.
 308
 309   @param[in]  Interface         The interface used by the IpInstance
 310
 311 **/
 312 VOID
 313 Ip4CancelReceive (
 314   IN IP4_INTERFACE  *Interface
 315   );
 316
 317 /**
 318   Request to receive the packet from the interface.
 319
 320   @param[in]  Interface         The interface to receive the frames from.
 321   @param[in]  IpInstance        The instance that requests the receive. NULL for
 322                                 the driver itself.
 323   @param[in]  CallBack          Function to call when receive finished.
 324   @param[in]  Context           Opaque parameter to the callback.
 325
 326   @retval EFI_ALREADY_STARTED   There is already a pending receive request.
 327   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource to receive.
 328   @retval EFI_SUCCESS           The receive request has been started.
 329   @retval other                 Other error occurs.
 330
 331 **/
 332 EFI_STATUS
 333 Ip4ReceiveFrame (
 334   IN  IP4_INTERFACE       *Interface,
 335   IN  IP4_PROTOCOL        *IpInstance       OPTIONAL,
 336   IN  IP4_FRAME_CALLBACK  CallBack,
 337   IN  VOID                *Context
 338   );
 339
 340 #endif