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