MdeModulePkg/Include/Library/UdpIoLib.h

   1 /** @file
   2   The helper routines to access UDP service. It is used by both
   3   DHCP and MTFTP.
   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 _UDP4IO_H_
  17 #define _UDP4IO_H_
  18
  19 #include <PiDxe.h>
  20
  21 #include <Protocol/Udp4.h>
  22
  23 #include <Library/UdpIoLib.h>
  24 #include <Library/NetLib.h>
  25
  26 typedef struct _UDP_IO_PORT UDP_IO_PORT;
  27
  28 typedef enum {
  29   UDP_IO_RX_SIGNATURE = EFI_SIGNATURE_32 ('U', 'D', 'P', 'R'),
  30   UDP_IO_TX_SIGNATURE = EFI_SIGNATURE_32 ('U', 'D', 'P', 'T'),
  31   UDP_IO_SIGNATURE    = EFI_SIGNATURE_32 ('U', 'D', 'P', 'I')
  32 } UDP_IO_SIGNATURE_TYPE;
  33
  34 typedef struct {
  35   IP4_ADDR                  LocalAddr;
  36   UINT16                    LocalPort;
  37   IP4_ADDR                  RemoteAddr;
  38   UINT16                    RemotePort;
  39 } UDP_POINTS;
  40
  41 //
  42 // This prototype is used by both receive and transmission.
  43 // When receiving Netbuf is allocated by UDP access point, and
  44 // released by user. When transmitting, the NetBuf is from user,
  45 // and provided to the callback as a reference.
  46 //
  47 typedef
  48 VOID
  49 (*UDP_IO_CALLBACK) (
  50   IN NET_BUF                *Packet,
  51   IN UDP_POINTS             *Points,
  52   IN EFI_STATUS             IoStatus,
  53   IN VOID                   *Context
  54   );
  55
  56 //
  57 // Each receive request is wrapped in an UDP_RX_TOKEN. Upon completion,
  58 // the CallBack will be called. Only one receive request is send to UDP.
  59 // HeadLen gives the length of the application's header. UDP_IO will
  60 // make the application's header continous before delivery up.
  61 //
  62 typedef struct {
  63   UINT32                    Signature;
  64   UDP_IO_PORT               *UdpIo;
  65
  66   UDP_IO_CALLBACK           CallBack;
  67   VOID                      *Context;
  68
  69   UINT32                    HeadLen;
  70   EFI_UDP4_COMPLETION_TOKEN UdpToken;
  71 } UDP_RX_TOKEN;
  72
  73 //
  74 // Each transmit request is wrapped in an UDP_TX_TOKEN. Upon completion,
  75 // the CallBack will be called. There can be several transmit requests.
  76 //
  77 typedef struct {
  78   UINT32                    Signature;
  79   LIST_ENTRY                Link;
  80   UDP_IO_PORT               *UdpIo;
  81
  82   UDP_IO_CALLBACK           CallBack;
  83   NET_BUF                   *Packet;
  84   VOID                      *Context;
  85
  86   EFI_UDP4_SESSION_DATA     UdpSession;
  87   EFI_IPv4_ADDRESS          Gateway;
  88
  89   EFI_UDP4_COMPLETION_TOKEN UdpToken;
  90   EFI_UDP4_TRANSMIT_DATA    UdpTxData;
  91 } UDP_TX_TOKEN;
  92
  93 struct _UDP_IO_PORT {
  94   UINT32                    Signature;
  95   LIST_ENTRY                Link;
  96   INTN                      RefCnt;
  97
  98   //
  99   // Handle used to create/destory UDP child
 100   //
 101   EFI_HANDLE                Controller;
 102   EFI_HANDLE                Image;
 103   EFI_HANDLE                UdpHandle;
 104
 105   EFI_UDP4_PROTOCOL         *Udp;
 106   EFI_UDP4_CONFIG_DATA      UdpConfig;
 107   EFI_SIMPLE_NETWORK_MODE   SnpMode;
 108
 109   LIST_ENTRY                SentDatagram;
 110   UDP_RX_TOKEN              *RecvRequest;
 111 };
 112
 113 typedef
 114 EFI_STATUS
 115 (*UDP_IO_CONFIG) (
 116   IN UDP_IO_PORT            *UdpIo,
 117   IN VOID                   *Context
 118   );
 119
 120 typedef
 121 BOOLEAN
 122 (*UDP_IO_TO_CANCEL) (
 123   IN UDP_TX_TOKEN           *Token,
 124   IN VOID                   *Context
 125   );
 126
 127 /**
 128   Create a UDP IO port to access the UDP service. It will
 129   create and configure a UDP child.
 130
 131   @param  Controller            The controller that has the UDP service binding
 132                                 protocol installed.
 133   @param  ImageHandle           The image handle for the driver.
 134   @param  Configure             The function to configure the created UDP child
 135   @param  Context               The opaque parameter for the Configure funtion.
 136
 137   @return A point to just created UDP IO port or NULL if failed.
 138
 139 **/
 140 UDP_IO_PORT *
 141 EFIAPI
 142 UdpIoCreatePort (
 143   IN  EFI_HANDLE            Controller,
 144   IN  EFI_HANDLE            ImageHandle,
 145   IN  UDP_IO_CONFIG         Configure,
 146   IN  VOID                  *Context
 147   );
 148
 149 /**
 150   Free the UDP IO port and all its related resources including
 151   all the transmitted packet.
 152
 153   @param  UdpIo                 The UDP IO port to free.
 154
 155   @retval EFI_SUCCESS           The UDP IO port is freed.
 156
 157 **/
 158 EFI_STATUS
 159 EFIAPI
 160 UdpIoFreePort (
 161   IN  UDP_IO_PORT           *UdpIo
 162   );
 163
 164 /**
 165   Clean up the UDP IO port. It will release all the transmitted
 166   datagrams and receive request. It will also configure NULL the
 167   UDP child.
 168
 169   @param  UdpIo                 UDP IO port to clean up.
 170
 171   @return None
 172
 173 **/
 174 VOID
 175 EFIAPI
 176 UdpIoCleanPort (
 177   IN  UDP_IO_PORT           *UdpIo
 178   );
 179
 180 /**
 181   Send a packet through the UDP IO port.
 182
 183   @param  UdpIo                 The UDP IO Port to send the packet through
 184   @param  Packet                The packet to send
 185   @param  EndPoint              The local and remote access point
 186   @param  Gateway               The gateway to use
 187   @param  CallBack              The call back function to call when packet is
 188                                 transmitted or failed.
 189   @param  Context               The opque parameter to the CallBack
 190
 191   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the packet
 192   @retval EFI_SUCCESS           The packet is successfully delivered to UDP  for
 193                                 transmission.
 194
 195 **/
 196 EFI_STATUS
 197 EFIAPI
 198 UdpIoSendDatagram (
 199   IN  UDP_IO_PORT           *UdpIo,
 200   IN  NET_BUF               *Packet,
 201   IN  UDP_POINTS            *EndPoint, OPTIONAL
 202   IN  IP4_ADDR              Gateway,
 203   IN  UDP_IO_CALLBACK       CallBack,
 204   IN  VOID                  *Context
 205   );
 206
 207 /**
 208   Cancel a single sent datagram.
 209
 210   @param  UdpIo                 The UDP IO port to cancel the packet from
 211   @param  Packet                The packet to cancel
 212
 213   @return None
 214
 215 **/
 216 VOID
 217 EFIAPI
 218 UdpIoCancelSentDatagram (
 219   IN  UDP_IO_PORT           *UdpIo,
 220   IN  NET_BUF               *Packet
 221   );
 222
 223 /**
 224   Issue a receive request to the UDP IO port.
 225
 226   @param  UdpIo                 The UDP IO port to recieve the packet from.
 227   @param  CallBack              The call back function to execute when receive
 228                                 finished.
 229   @param  Context               The opque context to the call back
 230   @param  HeadLen               The lenght of the application's header
 231
 232   @retval EFI_ALREADY_STARTED   There is already a pending receive request. Only
 233                                 one receive request is supported.
 234   @retval EFI_OUT_OF_RESOURCES  Failed to allocate some resource.
 235   @retval EFI_SUCCESS           The receive request is issued successfully.
 236
 237 **/
 238 EFI_STATUS
 239 EFIAPI
 240 UdpIoRecvDatagram (
 241   IN  UDP_IO_PORT           *UdpIo,
 242   IN  UDP_IO_CALLBACK       CallBack,
 243   IN  VOID                  *Context,
 244   IN  UINT32                HeadLen
 245   );
 246 #endif