1/** @file
2  Support functions declaration for UefiPxeBc Driver.
3
4  Copyright (c) 2007 - 2014, 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**/
40EFI_STATUS
41PxeBcFlushStationIp (
42  PXEBC_PRIVATE_DATA       *Private,
43  EFI_IP_ADDRESS           *StationIp,
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**/
55VOID
56EFIAPI
57PxeBcCommonNotify (
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**/
75BOOLEAN
76PxeBcCheckArpCache (
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**/
90VOID
91EFIAPI
92PxeBcArpCacheUpdate (
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**/
105VOID
106EFIAPI
107PxeBcIcmpErrorUpdate (
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**/
120VOID
121EFIAPI
122PxeBcIcmp6ErrorUpdate (
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                 Pointer to EFI_UDP4_PROTOCOL.
132  @param[in]       StationIp            Pointer to the station address.
133  @param[in]       SubnetMask           Pointer to the subnet mask.
134  @param[in]       Gateway              Pointer to the gateway address.
135  @param[in, out]  SrcPort              Pointer to the source port.
136  @param[in]       DoNotFragment        The flag of DoNotFragment bit in the IPv4
137                                        packet.
138
139  @retval          EFI_SUCCESS          Successfully configured this instance.
140  @retval          Others               Failed to configure this instance.
141
142**/
143EFI_STATUS
144PxeBcConfigUdp4Write (
145  IN     EFI_UDP4_PROTOCOL  *Udp4,
146  IN     EFI_IPv4_ADDRESS   *StationIp,
147  IN     EFI_IPv4_ADDRESS   *SubnetMask,
148  IN     EFI_IPv4_ADDRESS   *Gateway,
149  IN OUT UINT16             *SrcPort,
150  IN     BOOLEAN            DoNotFragment
151  );
152
153
154/**
155  This function is to configure a UDPv6 instance for UdpWrite.
156
157  @param[in]       Udp6                 Pointer to EFI_UDP6_PROTOCOL.
158  @param[in]       StationIp            Pointer to the station address.
159  @param[in, out]  SrcPort              Pointer to the source port.
160
161  @retval          EFI_SUCCESS          Successfuly configured this instance.
162  @retval          Others               Failed to configure this instance.
163
164**/
165EFI_STATUS
166PxeBcConfigUdp6Write (
167  IN     EFI_UDP6_PROTOCOL  *Udp6,
168  IN     EFI_IPv6_ADDRESS   *StationIp,
169  IN OUT UINT16             *SrcPort
170  );
171
172/**
173  This function is to configure a UDPv4 instance for UdpWrite.
174
175  @param[in]       Udp4                 Pointer to EFI_UDP4_PROTOCOL.
176  @param[in]       Session              Pointer to the UDP4 session data.
177  @param[in]       TimeoutEvent         The event for timeout.
178  @param[in]       Gateway              Pointer to the gateway address.
179  @param[in]       HeaderSize           An optional field which may be set to the length of a header
180                                        at HeaderPtr to be prefixed to the data at BufferPtr.
181  @param[in]       HeaderPtr            If HeaderSize is not NULL, a pointer to a header to be
182                                        prefixed to the data at BufferPtr.
183  @param[in]       BufferSize           A pointer to the size of the data at BufferPtr.
184  @param[in]       BufferPtr            A pointer to the data to be written.
185
186  @retval          EFI_SUCCESS          Successfully sent out data with Udp4Write.
187  @retval          Others               Failed to send out data.
188
189**/
190EFI_STATUS
191PxeBcUdp4Write (
192  IN EFI_UDP4_PROTOCOL       *Udp4,
193  IN EFI_UDP4_SESSION_DATA   *Session,
194  IN EFI_EVENT               TimeoutEvent,
195  IN EFI_IPv4_ADDRESS        *Gateway      OPTIONAL,
196  IN UINTN                   *HeaderSize   OPTIONAL,
197  IN VOID                    *HeaderPtr    OPTIONAL,
198  IN UINTN                   *BufferSize,
199  IN VOID                    *BufferPtr
200  );
201
202
203/**
204  This function is to configure a UDPv6 instance for UdpWrite.
205
206  @param[in]       Udp6                 Pointer to EFI_UDP6_PROTOCOL.
207  @param[in]       Session              Pointer to the UDP6 session data.
208  @param[in]       TimeoutEvent         The event for timeout.
209  @param[in]       HeaderSize           An optional field which may be set to the length of a header
210                                        at HeaderPtr to be prefixed to the data at BufferPtr.
211  @param[in]       HeaderPtr            If HeaderSize is not NULL, a pointer to a header to be
212                                        prefixed to the data at BufferPtr.
213  @param[in]       BufferSize           A pointer to the size of the data at BufferPtr.
214  @param[in]       BufferPtr            A pointer to the data to be written.
215
216  @retval          EFI_SUCCESS          Successfully to send out data with Udp6Write.
217  @retval          Others               Failed to send out data.
218
219**/
220EFI_STATUS
221PxeBcUdp6Write (
222  IN EFI_UDP6_PROTOCOL       *Udp6,
223  IN EFI_UDP6_SESSION_DATA   *Session,
224  IN EFI_EVENT               TimeoutEvent,
225  IN UINTN                   *HeaderSize   OPTIONAL,
226  IN VOID                    *HeaderPtr    OPTIONAL,
227  IN UINTN                   *BufferSize,
228  IN VOID                    *BufferPtr
229  );
230
231
232/**
233  Check the received packet with the Ip filter.
234
235  @param[in]  Mode                Pointer to mode data of PxeBc.
236  @param[in]  Session             Pointer to the current UDPv4 session.
237  @param[in]  OpFlags             Operation flag for UdpRead/UdpWrite.
238
239  @retval     TRUE                Succesfully passed the Ip filter.
240  @retval     FALSE               Failed to pass the Ip filter.
241
242**/
243BOOLEAN
244PxeBcCheckByIpFilter (
245  IN EFI_PXE_BASE_CODE_MODE    *Mode,
246  IN VOID                      *Session,
247  IN UINT16                    OpFlags
248  );
249
250
251/**
252  Filter the received packet with the destination Ip.
253
254  @param[in]       Mode           Pointer to mode data of PxeBc.
255  @param[in]       Session        Pointer to the current UDPv4 session.
256  @param[in, out]  DestIp         Pointer to the dest Ip address.
257  @param[in]       OpFlags        Operation flag for UdpRead/UdpWrite.
258
259  @retval     TRUE                Succesfully passed the IPv4 filter.
260  @retval     FALSE               Failed to pass the IPv4 filter.
261
262**/
263BOOLEAN
264PxeBcCheckByDestIp (
265  IN     EFI_PXE_BASE_CODE_MODE    *Mode,
266  IN     VOID                      *Session,
267  IN OUT EFI_IP_ADDRESS            *DestIp,
268  IN     UINT16                    OpFlags
269  );
270
271
272/**
273  Check the received packet with the destination port.
274
275  @param[in]       Mode           Pointer to mode data of PxeBc.
276  @param[in]       Session        Pointer to the current UDPv4 session.
277  @param[in, out]  DestPort       Pointer to the destination port.
278  @param[in]       OpFlags        Operation flag for UdpRead/UdpWrite.
279
280  @retval     TRUE                Succesfully passed the IPv4 filter.
281  @retval     FALSE               Failed to pass the IPv4 filter.
282
283**/
284BOOLEAN
285PxeBcCheckByDestPort (
286  IN     EFI_PXE_BASE_CODE_MODE    *Mode,
287  IN     VOID                      *Session,
288  IN OUT UINT16                    *DestPort,
289  IN     UINT16                    OpFlags
290  );
291
292
293/**
294  Filter the received packet with the source Ip.
295
296  @param[in]       Mode           Pointer to mode data of PxeBc.
297  @param[in]       Session        Pointer to the current UDPv4 session.
298  @param[in, out]  SrcIp          Pointer to the source Ip address.
299  @param[in]       OpFlags        Operation flag for UdpRead/UdpWrite.
300
301  @retval     TRUE                Succesfully passed the IPv4 filter.
302  @retval     FALSE               Failed to pass the IPv4 filter.
303
304**/
305BOOLEAN
306PxeBcFilterBySrcIp (
307  IN     EFI_PXE_BASE_CODE_MODE    *Mode,
308  IN     VOID                      *Session,
309  IN OUT EFI_IP_ADDRESS            *SrcIp,
310  IN     UINT16                    OpFlags
311  );
312
313
314/**
315  Filter the received packet with the source port.
316
317  @param[in]       Mode           Pointer to mode data of PxeBc.
318  @param[in]       Session        Pointer to the current UDPv4 session.
319  @param[in, out]  SrcPort        Pointer to the source port.
320  @param[in]       OpFlags        Operation flag for UdpRead/UdpWrite.
321
322  @retval     TRUE                Succesfully passed the IPv4 filter.
323  @retval     FALSE               Failed to pass the IPv4 filter.
324
325**/
326BOOLEAN
327PxeBcFilterBySrcPort (
328  IN     EFI_PXE_BASE_CODE_MODE    *Mode,
329  IN     VOID                      *Session,
330  IN OUT UINT16                    *SrcPort,
331  IN     UINT16                    OpFlags
332  );
333
334
335/**
336  This function is to receive packet with Udp4Read.
337
338  @param[in]       Udp4                 Pointer to EFI_UDP4_PROTOCOL.
339  @param[in]       Token                Pointer to EFI_UDP4_COMPLETION_TOKEN.
340  @param[in]       Mode                 Pointer to EFI_PXE_BASE_CODE_MODE.
341  @param[in]       TimeoutEvent         The event for timeout.
342  @param[in]       OpFlags              The UDP operation flags.
343  @param[in]       IsDone               Pointer to IsDone flag.
344  @param[out]      IsMatched            Pointer to IsMatched flag.
345  @param[in, out]  DestIp               Pointer to destination address.
346  @param[in, out]  DestPort             Pointer to destination port.
347  @param[in, out]  SrcIp                Pointer to source address.
348  @param[in, out]  SrcPort              Pointer to source port.
349
350  @retval          EFI_SUCCESS          Successfully read data with Udp4.
351  @retval          Others               Failed to send out data.
352
353**/
354EFI_STATUS
355PxeBcUdp4Read (
356  IN     EFI_UDP4_PROTOCOL            *Udp4,
357  IN     EFI_UDP4_COMPLETION_TOKEN    *Token,
358  IN     EFI_PXE_BASE_CODE_MODE       *Mode,
359  IN     EFI_EVENT                    TimeoutEvent,
360  IN     UINT16                       OpFlags,
361  IN     BOOLEAN                      *IsDone,
362     OUT BOOLEAN                      *IsMatched,
363  IN OUT EFI_IP_ADDRESS               *DestIp      OPTIONAL,
364  IN OUT EFI_PXE_BASE_CODE_UDP_PORT   *DestPort    OPTIONAL,
365  IN OUT EFI_IP_ADDRESS               *SrcIp       OPTIONAL,
366  IN OUT EFI_PXE_BASE_CODE_UDP_PORT   *SrcPort     OPTIONAL
367  );
368
369
370/**
371  This function is to receive packet with Udp6Read.
372
373  @param[in]       Udp6                 Pointer to EFI_UDP6_PROTOCOL.
374  @param[in]       Token                Pointer to EFI_UDP6_COMPLETION_TOKEN.
375  @param[in]       Mode                 Pointer to EFI_PXE_BASE_CODE_MODE.
376  @param[in]       TimeoutEvent         The event for timeout.
377  @param[in]       OpFlags              The UDP operation flags.
378  @param[in]       IsDone               Pointer to IsDone flag.
379  @param[out]      IsMatched            Pointer to IsMatched flag.
380  @param[in, out]  DestIp               Pointer to destination address.
381  @param[in, out]  DestPort             Pointer to destination port.
382  @param[in, out]  SrcIp                Pointer to source address.
383  @param[in, out]  SrcPort              Pointer to source port.
384
385  @retval          EFI_SUCCESS          Successfully read data with Udp6.
386  @retval          Others               Failed to send out data.
387
388**/
389EFI_STATUS
390PxeBcUdp6Read (
391  IN     EFI_UDP6_PROTOCOL            *Udp6,
392  IN     EFI_UDP6_COMPLETION_TOKEN    *Token,
393  IN     EFI_PXE_BASE_CODE_MODE       *Mode,
394  IN     EFI_EVENT                    TimeoutEvent,
395  IN     UINT16                       OpFlags,
396  IN     BOOLEAN                      *IsDone,
397     OUT BOOLEAN                      *IsMatched,
398  IN OUT EFI_IP_ADDRESS               *DestIp      OPTIONAL,
399  IN OUT EFI_PXE_BASE_CODE_UDP_PORT   *DestPort    OPTIONAL,
400  IN OUT EFI_IP_ADDRESS               *SrcIp       OPTIONAL,
401  IN OUT EFI_PXE_BASE_CODE_UDP_PORT   *SrcPort     OPTIONAL
402  );
403
404
405/**
406  This function is to display the IPv4 address.
407
408  @param[in]  Ip        Pointer to the IPv4 address.
409
410**/
411VOID
412PxeBcShowIp4Addr (
413  IN EFI_IPv4_ADDRESS   *Ip
414  );
415
416
417/**
418  This function is to display the IPv6 address.
419
420  @param[in]  Ip        Pointer to the IPv6 address.
421
422**/
423VOID
424PxeBcShowIp6Addr (
425  IN EFI_IPv6_ADDRESS   *Ip
426  );
427
428
429/**
430  This function is to convert UINTN to ASCII string with required format.
431
432  @param[in]  Number         Numeric value to be converted.
433  @param[in]  Buffer         Pointer to the buffer for ASCII string.
434  @param[in]  Length         Length of the required format.
435
436**/
437VOID
438PxeBcUintnToAscDecWithFormat (
439  IN UINTN                       Number,
440  IN UINT8                       *Buffer,
441  IN INTN                        Length
442  );
443
444
445/**
446  This function is to convert a UINTN to a ASCII string, and return the
447  actual length of the buffer.
448
449  @param[in]  Number         Numeric value to be converted.
450  @param[in]  Buffer         Pointer to the buffer for ASCII string.
451  @param[in]  BufferSize     The maxsize of the buffer.
452
453  @return     Length         The actual length of the ASCII string.
454
455**/
456UINTN
457PxeBcUintnToAscDec (
458  IN UINTN               Number,
459  IN UINT8               *Buffer,
460  IN UINTN               BufferSize
461  );
462
463/**
464  This function is to convert unicode hex number to a UINT8.
465
466  @param[out]  Digit                   The converted UINT8 for output.
467  @param[in]   Char                    The unicode hex number to be converted.
468
469  @retval      EFI_SUCCESS             Successfully converted the unicode hex.
470  @retval      EFI_INVALID_PARAMETER   Failed to convert the unicode hex.
471
472**/
473EFI_STATUS
474PxeBcUniHexToUint8 (
475  OUT UINT8                *Digit,
476  IN  CHAR16               Char
477  );
478
479/**
480  Calculate the elapsed time.
481
482  @param[in]      Private      The pointer to PXE private data
483
484**/
485VOID
486CalcElapsedTime (
487  IN     PXEBC_PRIVATE_DATA     *Private
488  );
489
490/**
491  Get the Nic handle using any child handle in the IPv4 stack.
492
493  @param[in]  ControllerHandle    Pointer to child handle over IPv4.
494
495  @return NicHandle               The pointer to the Nic handle.
496
497**/
498EFI_HANDLE
499PxeBcGetNicByIp4Children (
500  IN EFI_HANDLE                 ControllerHandle
501  );
502
503/**
504  Get the Nic handle using any child handle in the IPv6 stack.
505
506  @param[in]  ControllerHandle    Pointer to child handle over IPv6.
507
508  @return NicHandle               The pointer to the Nic handle.
509
510**/
511EFI_HANDLE
512PxeBcGetNicByIp6Children (
513  IN EFI_HANDLE                  ControllerHandle
514  );
515#endif
516