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