NetworkPkg/Include/Library/UdpIoLib.h

   1 /** @file
   2   This library is used to share code between UEFI network stack modules.
   3   It provides the helper routines to access UDP service. It is used by both DHCP and MTFTP.
   4
   5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _UDP_IO_H_
  11 #define _UDP_IO_H_
  12
  13 #include <Protocol/Udp4.h>
  14 #include <Protocol/Udp6.h>
  15
  16 #include <Library/NetLib.h>
  17
  18 typedef struct _UDP_IO UDP_IO;
  19
  20 ///
  21 /// Signatures used by UdpIo Library.
  22 ///
  23
  24 #define UDP_IO_RX_SIGNATURE  SIGNATURE_32 ('U', 'D', 'P', 'R')
  25 #define UDP_IO_TX_SIGNATURE  SIGNATURE_32 ('U', 'D', 'P', 'T')
  26 #define UDP_IO_SIGNATURE     SIGNATURE_32 ('U', 'D', 'P', 'I')
  27
  28 #define UDP_IO_UDP4_VERSION  4
  29 #define UDP_IO_UDP6_VERSION  6
  30
  31 ///
  32 /// The UDP address pair.
  33 ///
  34 typedef struct {
  35   EFI_IP_ADDRESS    LocalAddr;
  36   UINT16            LocalPort;
  37   EFI_IP_ADDRESS    RemoteAddr;
  38   UINT16            RemotePort;
  39 } UDP_END_POINT;
  40
  41 /**
  42   Prototype called when receiving or sending packets to or from a UDP point.
  43
  44   This prototype is used by both receive and sending when calling
  45   UdpIoRecvDatagram() or UdpIoSendDatagram(). When receiving, Netbuf is allocated by the
  46   UDP access point and released by the user. When sending, the user allocates the NetBuf,
  47   which is then provided to the callback as a reference.
  48
  49   @param[in] Packet       The packet received or sent.
  50   @param[in] EndPoint     The UDP address pair corresponds to the UDP IO.
  51   @param[in] IoStatus     The packet receiving or sending status.
  52   @param[in] Context      The user-defined data when calling UdpIoRecvDatagram() or
  53                           UdpIoSendDatagram().
  54 **/
  55 typedef
  56 VOID
  57 (EFIAPI *UDP_IO_CALLBACK)(
  58   IN NET_BUF                *Packet,
  59   IN UDP_END_POINT          *EndPoint,
  60   IN EFI_STATUS             IoStatus,
  61   IN VOID                   *Context
  62   );
  63
  64 ///
  65 /// This structure is used internally by the UdpIo Library.
  66 ///
  67 /// Each receive request is wrapped in an UDP_RX_TOKEN. Upon completion,
  68 /// the CallBack will be called. Only one receive request is sent to UDP at a
  69 /// time. HeadLen gives the length of the application's header. UDP_IO will
  70 /// make the application's header continuous before delivering up.
  71 ///
  72 typedef union {
  73   EFI_UDP4_COMPLETION_TOKEN    Udp4;
  74   EFI_UDP6_COMPLETION_TOKEN    Udp6;
  75 } UDP_COMPLETION_TOKEN;
  76
  77 typedef struct {
  78   UINT32                  Signature;
  79   UDP_IO                  *UdpIo;
  80
  81   UDP_IO_CALLBACK         CallBack;
  82   VOID                    *Context;
  83   UINT32                  HeadLen;
  84
  85   UDP_COMPLETION_TOKEN    Token;
  86 } UDP_RX_TOKEN;
  87
  88 ///
  89 /// This structure is used internally by UdpIo Library.
  90 ///
  91 /// Each transmit request is wrapped in an UDP_TX_TOKEN. Upon completion,
  92 /// the CallBack will be called. There can be several transmit requests. All transmit
  93 /// requests are linked in a list.
  94 ///
  95
  96 typedef union {
  97   EFI_UDP4_SESSION_DATA    Udp4;
  98   EFI_UDP6_SESSION_DATA    Udp6;
  99 } UDP_SESSION_DATA;
 100
 101 typedef union {
 102   EFI_UDP4_TRANSMIT_DATA    Udp4;
 103   EFI_UDP6_TRANSMIT_DATA    Udp6;
 104 } UDP_TRANSMIT_DATA;
 105
 106 typedef struct {
 107   UINT32                  Signature;
 108   LIST_ENTRY              Link;
 109   UDP_IO                  *UdpIo;
 110   UDP_IO_CALLBACK         CallBack;
 111   NET_BUF                 *Packet;
 112   VOID                    *Context;
 113   EFI_IPv4_ADDRESS        Gateway;
 114   UDP_SESSION_DATA        Session;
 115   UDP_COMPLETION_TOKEN    Token;
 116   UDP_TRANSMIT_DATA       Data;
 117 } UDP_TX_TOKEN;
 118
 119 ///
 120 /// Type defined as UDP_IO.
 121 ///
 122 /// This data structure wraps the UDP instance and configuration.
 123 /// UdpIo Library uses this structure for all Udp4 or Udp6 operations.
 124 ///
 125 struct _UDP_IO {
 126   UINT32                     Signature;
 127   LIST_ENTRY                 Link;
 128   INTN                       RefCnt;
 129   UINT8                      UdpVersion;
 130
 131   //
 132   // Handle used to create/destroy UDP child
 133   //
 134   EFI_HANDLE                 Controller;
 135   EFI_HANDLE                 Image;
 136   EFI_HANDLE                 UdpHandle;
 137
 138   EFI_SIMPLE_NETWORK_MODE    SnpMode;
 139
 140   LIST_ENTRY                 SentDatagram;  ///< A list of UDP_TX_TOKEN.
 141   UDP_RX_TOKEN               *RecvRequest;
 142
 143   union {
 144     EFI_UDP4_PROTOCOL    *Udp4;
 145     EFI_UDP6_PROTOCOL    *Udp6;
 146   } Protocol;
 147
 148   union {
 149     EFI_UDP4_CONFIG_DATA    Udp4;
 150     EFI_UDP6_CONFIG_DATA    Udp6;
 151   } Config;
 152 };
 153
 154 /**
 155   The prototype called when UdpIo Library configures a UDP instance.
 156
 157   The prototype is set and called when creating a UDP_IO in UdpIoCreatePort().
 158
 159   @param[in] UdpIo         The UDP_IO to configure.
 160   @param[in] Context       The user-defined data when calling UdpIoCreatePort().
 161
 162   @retval EFI_SUCCESS  The configuration succeeded.
 163   @retval Others       The UDP_IO fails to configure indicating
 164                        UdpIoCreatePort() should fail.
 165 **/
 166 typedef
 167 EFI_STATUS
 168 (EFIAPI *UDP_IO_CONFIG)(
 169   IN UDP_IO                 *UdpIo,
 170   IN VOID                   *Context
 171   );
 172
 173 /**
 174   The select function to decide whether to cancel the UDP_TX_TOKEN.
 175
 176   @param[in] Token        The UDP_TX_TOKEN to decide whether to cancel.
 177   @param[in] Context      User-defined data in UdpIoCancelDgrams().
 178
 179   @retval TRUE        Cancel the UDP_TX_TOKEN.
 180   @retval FALSE       Do not cancel this UDP_TX_TOKEN.
 181
 182 **/
 183 typedef
 184 BOOLEAN
 185 (EFIAPI *UDP_IO_TO_CANCEL)(
 186   IN UDP_TX_TOKEN           *Token,
 187   IN VOID                   *Context
 188   );
 189
 190 /**
 191   Cancel all the sent datagram that pass the selection criteria of ToCancel.
 192
 193   If ToCancel is NULL, all the datagrams are cancelled.
 194   If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().
 195
 196   @param[in]  UdpIo                 The UDP_IO to cancel packet.
 197   @param[in]  IoStatus              The IoStatus to return to the packet owners.
 198   @param[in]  ToCancel              The select function to test whether to cancel this
 199                                     packet or not.
 200   @param[in]  Context               The opaque parameter to the ToCancel.
 201
 202 **/
 203 VOID
 204 EFIAPI
 205 UdpIoCancelDgrams (
 206   IN UDP_IO            *UdpIo,
 207   IN EFI_STATUS        IoStatus,
 208   IN UDP_IO_TO_CANCEL  ToCancel         OPTIONAL,
 209   IN VOID              *Context         OPTIONAL
 210   );
 211
 212 /**
 213   Creates a UDP_IO to access the UDP service. It creates and configures
 214   a UDP child.
 215
 216   If Configure is NULL, then ASSERT().
 217   If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().
 218
 219   It locates the UDP service binding prototype on the Controller parameter
 220   uses the UDP service binding prototype to create a UDP child (also known as
 221   a UDP instance) configures the UDP child by calling Configure function prototype.
 222   Any failures in creating or configuring the UDP child return NULL for failure.
 223
 224   @param[in]  Controller            The controller that has the UDP service binding.
 225                                     protocol installed.
 226   @param[in]  ImageHandle           The image handle for the driver.
 227   @param[in]  Configure             The function to configure the created UDP child.
 228   @param[in]  UdpVersion            The UDP protocol version, UDP4 or UDP6.
 229   @param[in]  Context               The opaque parameter for the Configure function.
 230
 231   @return The newly-created UDP_IO, or NULL if failed.
 232
 233 **/
 234 UDP_IO *
 235 EFIAPI
 236 UdpIoCreateIo (
 237   IN  EFI_HANDLE     Controller,
 238   IN  EFI_HANDLE     ImageHandle,
 239   IN  UDP_IO_CONFIG  Configure,
 240   IN  UINT8          UdpVersion,
 241   IN  VOID           *Context
 242   );
 243
 244 /**
 245   Free the UDP_IO and all its related resources.
 246
 247   If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().
 248
 249   The function cancels all sent datagrams and receive requests.
 250
 251   @param[in]  UdpIo             The UDP_IO to free.
 252
 253   @retval EFI_SUCCESS           The UDP_IO is freed.
 254   @retval Others                Failed to free UDP_IO.
 255
 256 **/
 257 EFI_STATUS
 258 EFIAPI
 259 UdpIoFreeIo (
 260   IN  UDP_IO  *UdpIo
 261   );
 262
 263 /**
 264   Cleans up the UDP_IO without freeing it. Call this function
 265   if you intend to later re-use the UDP_IO.
 266
 267   If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().
 268
 269   This function releases all transmitted datagrams and receive requests and configures NULL for the UDP instance.
 270
 271   @param[in]  UdpIo                 The UDP_IO to clean up.
 272
 273 **/
 274 VOID
 275 EFIAPI
 276 UdpIoCleanIo (
 277   IN  UDP_IO  *UdpIo
 278   );
 279
 280 /**
 281   Send a packet through the UDP_IO.
 282
 283   If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().
 284
 285   The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called
 286   when the packet is sent. The optional parameter EndPoint overrides the default
 287   address pair if specified.
 288
 289   @param[in]  UdpIo                 The UDP_IO to send the packet through.
 290   @param[in]  Packet                The packet to send.
 291   @param[in]  EndPoint              The local and remote access point. Override the
 292                                     default address pair set during configuration.
 293   @param[in]  Gateway               The gateway to use.
 294   @param[in]  CallBack              The function being called when packet is
 295                                     transmitted or failed.
 296   @param[in]  Context               The opaque parameter passed to CallBack.
 297
 298   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the packet.
 299   @retval EFI_SUCCESS           The packet is successfully delivered to UDP for
 300                                 transmission.
 301
 302 **/
 303 EFI_STATUS
 304 EFIAPI
 305 UdpIoSendDatagram (
 306   IN  UDP_IO           *UdpIo,
 307   IN  NET_BUF          *Packet,
 308   IN  UDP_END_POINT    *EndPoint OPTIONAL,
 309   IN  EFI_IP_ADDRESS   *Gateway  OPTIONAL,
 310   IN  UDP_IO_CALLBACK  CallBack,
 311   IN  VOID             *Context
 312   );
 313
 314 /**
 315   Cancel a single sent datagram.
 316
 317   @param[in]  UdpIo                 The UDP_IO from which to cancel the packet
 318   @param[in]  Packet                The packet to cancel
 319
 320 **/
 321 VOID
 322 EFIAPI
 323 UdpIoCancelSentDatagram (
 324   IN  UDP_IO   *UdpIo,
 325   IN  NET_BUF  *Packet
 326   );
 327
 328 /**
 329   Issue a receive request to the UDP_IO.
 330
 331   If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().
 332
 333   This function is called when upper-layer needs packet from UDP for processing.
 334   Only one receive request is acceptable at a time. Therefore, one common usage model is
 335   to invoke this function inside its Callback function when the former packet
 336   is processed.
 337
 338   @param[in]  UdpIo                 The UDP_IO to receive the packet from.
 339   @param[in]  CallBack              The call back function to execute when the packet
 340                                     is received.
 341   @param[in]  Context               The opaque context passed to Callback.
 342   @param[in]  HeadLen               The length of the upper-layer's protocol header.
 343
 344   @retval EFI_ALREADY_STARTED   There is already a pending receive request. Only
 345                                 one receive request is supported at a time.
 346   @retval EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 347   @retval EFI_SUCCESS           The receive request was issued successfully.
 348   @retval EFI_UNSUPPORTED       The UDP version in UDP_IO is not supported.
 349
 350 **/
 351 EFI_STATUS
 352 EFIAPI
 353 UdpIoRecvDatagram (
 354   IN  UDP_IO           *UdpIo,
 355   IN  UDP_IO_CALLBACK  CallBack,
 356   IN  VOID             *Context,
 357   IN  UINT32           HeadLen
 358   );
 359
 360 #endif