NetworkPkg/UefiPxeBcDxe/PxeBcSupport.h

   1 /** @file
   2   Support functions declaration for UefiPxeBc Driver.
   3
   4   Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __EFI_PXEBC_SUPPORT_H__
  11 #define __EFI_PXEBC_SUPPORT_H__
  12
  13
  14 #define ICMP_DEST_UNREACHABLE      3
  15 #define ICMP_SOURCE_QUENCH         4
  16 #define ICMP_REDIRECT              5
  17 #define ICMP_ECHO_REQUEST          8
  18 #define ICMP_TIME_EXCEEDED         11
  19 #define ICMP_PARAMETER_PROBLEM     12
  20
  21
  22
  23 /**
  24   Flush the previous configuration using the new station Ip address.
  25
  26   @param[in]   Private        Pointer to PxeBc private data.
  27   @param[in]   StationIp      Pointer to the station Ip address.
  28   @param[in]   SubnetMask     Pointer to the subnet mask address for v4.
  29
  30   @retval EFI_SUCCESS         Successfully flushed the previous config.
  31   @retval Others              Failed to flush using the new station Ip.
  32
  33 **/
  34 EFI_STATUS
  35 PxeBcFlushStationIp (
  36   PXEBC_PRIVATE_DATA       *Private,
  37   EFI_IP_ADDRESS           *StationIp,     OPTIONAL
  38   EFI_IP_ADDRESS           *SubnetMask     OPTIONAL
  39   );
  40
  41
  42 /**
  43   Notify callback function when an event is triggered.
  44
  45   @param[in]  Event           The triggered event.
  46   @param[in]  Context         The opaque parameter to the function.
  47
  48 **/
  49 VOID
  50 EFIAPI
  51 PxeBcCommonNotify (
  52   IN EFI_EVENT           Event,
  53   IN VOID                *Context
  54   );
  55
  56
  57 /**
  58   Perform arp resolution from the arp cache in PxeBcMode.
  59
  60   @param  Mode           Pointer to EFI_PXE_BASE_CODE_MODE.
  61   @param  Ip4Addr        The Ip4 address for resolution.
  62   @param  MacAddress     The resolved MAC address if the resolution is successful.
  63                          The value is undefined if resolution fails.
  64
  65   @retval TRUE           Found a matched entry.
  66   @retval FALSE          Did not find a matched entry.
  67
  68 **/
  69 BOOLEAN
  70 PxeBcCheckArpCache (
  71   IN  EFI_PXE_BASE_CODE_MODE    *Mode,
  72   IN  EFI_IPv4_ADDRESS          *Ip4Addr,
  73   OUT EFI_MAC_ADDRESS           *MacAddress
  74   );
  75
  76
  77 /**
  78   Update arp cache periodically.
  79
  80   @param  Event              Pointer to EFI_PXE_BC_PROTOCOL.
  81   @param  Context            Context of the timer event.
  82
  83 **/
  84 VOID
  85 EFIAPI
  86 PxeBcArpCacheUpdate (
  87   IN EFI_EVENT    Event,
  88   IN VOID         *Context
  89   );
  90
  91
  92 /**
  93   xxx
  94
  95   @param  Event                 The event signaled.
  96   @param  Context               The context passed in by the event notifier.
  97
  98 **/
  99 VOID
 100 EFIAPI
 101 PxeBcIcmpErrorUpdate (
 102   IN EFI_EVENT             Event,
 103   IN VOID                  *Context
 104   );
 105
 106
 107 /**
 108   xxx
 109
 110   @param  Event                 The event signaled.
 111   @param  Context               The context passed in by the event notifier.
 112
 113 **/
 114 VOID
 115 EFIAPI
 116 PxeBcIcmp6ErrorUpdate (
 117   IN EFI_EVENT             Event,
 118   IN VOID                  *Context
 119   );
 120
 121
 122 /**
 123   This function is to configure a UDPv4 instance for UdpWrite.
 124
 125   @param[in]       Udp4                 The pointer to EFI_UDP4_PROTOCOL.
 126   @param[in]       StationIp            The pointer to the station address.
 127   @param[in]       SubnetMask           The pointer to the subnet mask.
 128   @param[in]       Gateway              The pointer to the gateway address.
 129   @param[in, out]  SrcPort              The pointer to the source port.
 130   @param[in]       DoNotFragment        If TRUE, fragment is not enabled.
 131                                         Otherwise, fragment is enabled.
 132   @param[in]       Ttl                  The time to live field of the IP header.
 133   @param[in]       ToS                  The type of service field of the IP header.
 134
 135   @retval          EFI_SUCCESS          Successfully configured this instance.
 136   @retval          Others               Failed to configure this instance.
 137
 138 **/
 139 EFI_STATUS
 140 PxeBcConfigUdp4Write (
 141   IN     EFI_UDP4_PROTOCOL  *Udp4,
 142   IN     EFI_IPv4_ADDRESS   *StationIp,
 143   IN     EFI_IPv4_ADDRESS   *SubnetMask,
 144   IN     EFI_IPv4_ADDRESS   *Gateway,
 145   IN OUT UINT16             *SrcPort,
 146   IN     BOOLEAN            DoNotFragment,
 147   IN     UINT8              Ttl,
 148   IN     UINT8              ToS
 149   );
 150
 151
 152 /**
 153   This function is to configure a UDPv6 instance for UdpWrite.
 154
 155   @param[in]       Udp6                 Pointer to EFI_UDP6_PROTOCOL.
 156   @param[in]       StationIp            Pointer to the station address.
 157   @param[in, out]  SrcPort              Pointer to the source port.
 158
 159   @retval          EFI_SUCCESS          Successfully configured this instance.
 160   @retval          Others               Failed to configure this instance.
 161
 162 **/
 163 EFI_STATUS
 164 PxeBcConfigUdp6Write (
 165   IN     EFI_UDP6_PROTOCOL  *Udp6,
 166   IN     EFI_IPv6_ADDRESS   *StationIp,
 167   IN OUT UINT16             *SrcPort
 168   );
 169
 170 /**
 171   This function is to configure a UDPv4 instance for UdpWrite.
 172
 173   @param[in]       Udp4                 Pointer to EFI_UDP4_PROTOCOL.
 174   @param[in]       Session              Pointer to the UDP4 session data.
 175   @param[in]       TimeoutEvent         The event for timeout.
 176   @param[in]       Gateway              Pointer to the gateway address.
 177   @param[in]       HeaderSize           An optional field which may be set to the length of a header
 178                                         at HeaderPtr to be prefixed to the data at BufferPtr.
 179   @param[in]       HeaderPtr            If HeaderSize is not NULL, a pointer to a header to be
 180                                         prefixed to the data at BufferPtr.
 181   @param[in]       BufferSize           A pointer to the size of the data at BufferPtr.
 182   @param[in]       BufferPtr            A pointer to the data to be written.
 183
 184   @retval          EFI_SUCCESS          Successfully sent out data with Udp4Write.
 185   @retval          Others               Failed to send out data.
 186
 187 **/
 188 EFI_STATUS
 189 PxeBcUdp4Write (
 190   IN EFI_UDP4_PROTOCOL       *Udp4,
 191   IN EFI_UDP4_SESSION_DATA   *Session,
 192   IN EFI_EVENT               TimeoutEvent,
 193   IN EFI_IPv4_ADDRESS        *Gateway      OPTIONAL,
 194   IN UINTN                   *HeaderSize   OPTIONAL,
 195   IN VOID                    *HeaderPtr    OPTIONAL,
 196   IN UINTN                   *BufferSize,
 197   IN VOID                    *BufferPtr
 198   );
 199
 200
 201 /**
 202   This function is to configure a UDPv6 instance for UdpWrite.
 203
 204   @param[in]       Udp6                 Pointer to EFI_UDP6_PROTOCOL.
 205   @param[in]       Session              Pointer to the UDP6 session data.
 206   @param[in]       TimeoutEvent         The event for timeout.
 207   @param[in]       HeaderSize           An optional field which may be set to the length of a header
 208                                         at HeaderPtr to be prefixed to the data at BufferPtr.
 209   @param[in]       HeaderPtr            If HeaderSize is not NULL, a pointer to a header to be
 210                                         prefixed to the data at BufferPtr.
 211   @param[in]       BufferSize           A pointer to the size of the data at BufferPtr.
 212   @param[in]       BufferPtr            A pointer to the data to be written.
 213
 214   @retval          EFI_SUCCESS          Successfully to send out data with Udp6Write.
 215   @retval          Others               Failed to send out data.
 216
 217 **/
 218 EFI_STATUS
 219 PxeBcUdp6Write (
 220   IN EFI_UDP6_PROTOCOL       *Udp6,
 221   IN EFI_UDP6_SESSION_DATA   *Session,
 222   IN EFI_EVENT               TimeoutEvent,
 223   IN UINTN                   *HeaderSize   OPTIONAL,
 224   IN VOID                    *HeaderPtr    OPTIONAL,
 225   IN UINTN                   *BufferSize,
 226   IN VOID                    *BufferPtr
 227   );
 228
 229
 230 /**
 231   Check the received packet with the Ip filter.
 232
 233   @param[in]  Mode                Pointer to mode data of PxeBc.
 234   @param[in]  Session             Pointer to the current UDPv4 session.
 235   @param[in]  OpFlags             Operation flag for UdpRead/UdpWrite.
 236
 237   @retval     TRUE                Successfully passed the Ip filter.
 238   @retval     FALSE               Failed to pass the Ip filter.
 239
 240 **/
 241 BOOLEAN
 242 PxeBcCheckByIpFilter (
 243   IN EFI_PXE_BASE_CODE_MODE    *Mode,
 244   IN VOID                      *Session,
 245   IN UINT16                    OpFlags
 246   );
 247
 248
 249 /**
 250   Filter the received packet with the destination Ip.
 251
 252   @param[in]       Mode           Pointer to mode data of PxeBc.
 253   @param[in]       Session        Pointer to the current UDPv4 session.
 254   @param[in, out]  DestIp         Pointer to the dest Ip address.
 255   @param[in]       OpFlags        Operation flag for UdpRead/UdpWrite.
 256
 257   @retval     TRUE                Successfully passed the IPv4 filter.
 258   @retval     FALSE               Failed to pass the IPv4 filter.
 259
 260 **/
 261 BOOLEAN
 262 PxeBcCheckByDestIp (
 263   IN     EFI_PXE_BASE_CODE_MODE    *Mode,
 264   IN     VOID                      *Session,
 265   IN OUT EFI_IP_ADDRESS            *DestIp,
 266   IN     UINT16                    OpFlags
 267   );
 268
 269
 270 /**
 271   Check the received packet with the destination port.
 272
 273   @param[in]       Mode           Pointer to mode data of PxeBc.
 274   @param[in]       Session        Pointer to the current UDPv4 session.
 275   @param[in, out]  DestPort       Pointer to the destination port.
 276   @param[in]       OpFlags        Operation flag for UdpRead/UdpWrite.
 277
 278   @retval     TRUE                Successfully passed the IPv4 filter.
 279   @retval     FALSE               Failed to pass the IPv4 filter.
 280
 281 **/
 282 BOOLEAN
 283 PxeBcCheckByDestPort (
 284   IN     EFI_PXE_BASE_CODE_MODE    *Mode,
 285   IN     VOID                      *Session,
 286   IN OUT UINT16                    *DestPort,
 287   IN     UINT16                    OpFlags
 288   );
 289
 290
 291 /**
 292   Filter the received packet with the source Ip.
 293
 294   @param[in]       Mode           Pointer to mode data of PxeBc.
 295   @param[in]       Session        Pointer to the current UDPv4 session.
 296   @param[in, out]  SrcIp          Pointer to the source Ip address.
 297   @param[in]       OpFlags        Operation flag for UdpRead/UdpWrite.
 298
 299   @retval     TRUE                Successfully passed the IPv4 filter.
 300   @retval     FALSE               Failed to pass the IPv4 filter.
 301
 302 **/
 303 BOOLEAN
 304 PxeBcFilterBySrcIp (
 305   IN     EFI_PXE_BASE_CODE_MODE    *Mode,
 306   IN     VOID                      *Session,
 307   IN OUT EFI_IP_ADDRESS            *SrcIp,
 308   IN     UINT16                    OpFlags
 309   );
 310
 311
 312 /**
 313   Filter the received packet with the source port.
 314
 315   @param[in]       Mode           Pointer to mode data of PxeBc.
 316   @param[in]       Session        Pointer to the current UDPv4 session.
 317   @param[in, out]  SrcPort        Pointer to the source port.
 318   @param[in]       OpFlags        Operation flag for UdpRead/UdpWrite.
 319
 320   @retval     TRUE                Successfully passed the IPv4 filter.
 321   @retval     FALSE               Failed to pass the IPv4 filter.
 322
 323 **/
 324 BOOLEAN
 325 PxeBcFilterBySrcPort (
 326   IN     EFI_PXE_BASE_CODE_MODE    *Mode,
 327   IN     VOID                      *Session,
 328   IN OUT UINT16                    *SrcPort,
 329   IN     UINT16                    OpFlags
 330   );
 331
 332
 333 /**
 334   This function is to receive packet with Udp4Read.
 335
 336   @param[in]       Udp4                 Pointer to EFI_UDP4_PROTOCOL.
 337   @param[in]       Token                Pointer to EFI_UDP4_COMPLETION_TOKEN.
 338   @param[in]       Mode                 Pointer to EFI_PXE_BASE_CODE_MODE.
 339   @param[in]       TimeoutEvent         The event for timeout.
 340   @param[in]       OpFlags              The UDP operation flags.
 341   @param[in]       IsDone               Pointer to IsDone flag.
 342   @param[out]      IsMatched            Pointer to IsMatched flag.
 343   @param[in, out]  DestIp               Pointer to destination address.
 344   @param[in, out]  DestPort             Pointer to destination port.
 345   @param[in, out]  SrcIp                Pointer to source address.
 346   @param[in, out]  SrcPort              Pointer to source port.
 347
 348   @retval          EFI_SUCCESS          Successfully read data with Udp4.
 349   @retval          Others               Failed to send out data.
 350
 351 **/
 352 EFI_STATUS
 353 PxeBcUdp4Read (
 354   IN     EFI_UDP4_PROTOCOL            *Udp4,
 355   IN     EFI_UDP4_COMPLETION_TOKEN    *Token,
 356   IN     EFI_PXE_BASE_CODE_MODE       *Mode,
 357   IN     EFI_EVENT                    TimeoutEvent,
 358   IN     UINT16                       OpFlags,
 359   IN     BOOLEAN                      *IsDone,
 360      OUT BOOLEAN                      *IsMatched,
 361   IN OUT EFI_IP_ADDRESS               *DestIp      OPTIONAL,
 362   IN OUT EFI_PXE_BASE_CODE_UDP_PORT   *DestPort    OPTIONAL,
 363   IN OUT EFI_IP_ADDRESS               *SrcIp       OPTIONAL,
 364   IN OUT EFI_PXE_BASE_CODE_UDP_PORT   *SrcPort     OPTIONAL
 365   );
 366
 367
 368 /**
 369   This function is to receive packet with Udp6Read.
 370
 371   @param[in]       Udp6                 Pointer to EFI_UDP6_PROTOCOL.
 372   @param[in]       Token                Pointer to EFI_UDP6_COMPLETION_TOKEN.
 373   @param[in]       Mode                 Pointer to EFI_PXE_BASE_CODE_MODE.
 374   @param[in]       TimeoutEvent         The event for timeout.
 375   @param[in]       OpFlags              The UDP operation flags.
 376   @param[in]       IsDone               Pointer to IsDone flag.
 377   @param[out]      IsMatched            Pointer to IsMatched flag.
 378   @param[in, out]  DestIp               Pointer to destination address.
 379   @param[in, out]  DestPort             Pointer to destination port.
 380   @param[in, out]  SrcIp                Pointer to source address.
 381   @param[in, out]  SrcPort              Pointer to source port.
 382
 383   @retval          EFI_SUCCESS          Successfully read data with Udp6.
 384   @retval          Others               Failed to send out data.
 385
 386 **/
 387 EFI_STATUS
 388 PxeBcUdp6Read (
 389   IN     EFI_UDP6_PROTOCOL            *Udp6,
 390   IN     EFI_UDP6_COMPLETION_TOKEN    *Token,
 391   IN     EFI_PXE_BASE_CODE_MODE       *Mode,
 392   IN     EFI_EVENT                    TimeoutEvent,
 393   IN     UINT16                       OpFlags,
 394   IN     BOOLEAN                      *IsDone,
 395      OUT BOOLEAN                      *IsMatched,
 396   IN OUT EFI_IP_ADDRESS               *DestIp      OPTIONAL,
 397   IN OUT EFI_PXE_BASE_CODE_UDP_PORT   *DestPort    OPTIONAL,
 398   IN OUT EFI_IP_ADDRESS               *SrcIp       OPTIONAL,
 399   IN OUT EFI_PXE_BASE_CODE_UDP_PORT   *SrcPort     OPTIONAL
 400   );
 401
 402
 403 /**
 404   This function is to display the IPv4 address.
 405
 406   @param[in]  Ip        Pointer to the IPv4 address.
 407
 408 **/
 409 VOID
 410 PxeBcShowIp4Addr (
 411   IN EFI_IPv4_ADDRESS   *Ip
 412   );
 413
 414
 415 /**
 416   This function is to display the IPv6 address.
 417
 418   @param[in]  Ip        Pointer to the IPv6 address.
 419
 420 **/
 421 VOID
 422 PxeBcShowIp6Addr (
 423   IN EFI_IPv6_ADDRESS   *Ip
 424   );
 425
 426
 427 /**
 428   This function is to convert UINTN to ASCII string with required format.
 429
 430   @param[in]  Number         Numeric value to be converted.
 431   @param[in]  Buffer         Pointer to the buffer for ASCII string.
 432   @param[in]  Length         Length of the required format.
 433
 434 **/
 435 VOID
 436 PxeBcUintnToAscDecWithFormat (
 437   IN UINTN                       Number,
 438   IN UINT8                       *Buffer,
 439   IN INTN                        Length
 440   );
 441
 442
 443 /**
 444   This function is to convert a UINTN to a ASCII string, and return the
 445   actual length of the buffer.
 446
 447   @param[in]  Number         Numeric value to be converted.
 448   @param[in]  Buffer         Pointer to the buffer for ASCII string.
 449   @param[in]  BufferSize     The maxsize of the buffer.
 450
 451   @return     Length         The actual length of the ASCII string.
 452
 453 **/
 454 UINTN
 455 PxeBcUintnToAscDec (
 456   IN UINTN               Number,
 457   IN UINT8               *Buffer,
 458   IN UINTN               BufferSize
 459   );
 460
 461 /**
 462   This function is to convert unicode hex number to a UINT8.
 463
 464   @param[out]  Digit                   The converted UINT8 for output.
 465   @param[in]   Char                    The unicode hex number to be converted.
 466
 467   @retval      EFI_SUCCESS             Successfully converted the unicode hex.
 468   @retval      EFI_INVALID_PARAMETER   Failed to convert the unicode hex.
 469
 470 **/
 471 EFI_STATUS
 472 PxeBcUniHexToUint8 (
 473   OUT UINT8                *Digit,
 474   IN  CHAR16               Char
 475   );
 476
 477 /**
 478   Calculate the elapsed time.
 479
 480   @param[in]      Private      The pointer to PXE private data
 481
 482 **/
 483 VOID
 484 CalcElapsedTime (
 485   IN     PXEBC_PRIVATE_DATA     *Private
 486   );
 487
 488 /**
 489   Get the Nic handle using any child handle in the IPv4 stack.
 490
 491   @param[in]  ControllerHandle    Pointer to child handle over IPv4.
 492
 493   @return NicHandle               The pointer to the Nic handle.
 494
 495 **/
 496 EFI_HANDLE
 497 PxeBcGetNicByIp4Children (
 498   IN EFI_HANDLE                 ControllerHandle
 499   );
 500
 501 /**
 502   Get the Nic handle using any child handle in the IPv6 stack.
 503
 504   @param[in]  ControllerHandle    Pointer to child handle over IPv6.
 505
 506   @return NicHandle               The pointer to the Nic handle.
 507
 508 **/
 509 EFI_HANDLE
 510 PxeBcGetNicByIp6Children (
 511   IN EFI_HANDLE                  ControllerHandle
 512   );
 513 #endif