xref: /illumos-gate/usr/src/boot/efi/include/Protocol/PxeBaseCodeCallBack.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   It is invoked when the PXE Base Code Protocol is about to transmit, has received,
3   or is waiting to receive a packet.
4 
5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
7 
8   @par Revision Reference:
9   This Protocol is introduced in EFI Specification 1.10
10 
11 **/
12 
13 #ifndef _PXE_BASE_CODE_CALLBACK_H_
14 #define _PXE_BASE_CODE_CALLBACK_H_
15 
16 ///
17 /// Call Back Definitions.
18 ///
19 #define EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL_GUID \
20   { \
21     0x245dca21, 0xfb7b, 0x11d3, {0x8f, 0x01, 0x00, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \
22   }
23 
24 ///
25 /// UEFI Revision Number Definition.
26 ///
27 #define EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL_REVISION  0x00010000
28 
29 ///
30 /// EFI 1.1 Revision Number defintion.
31 ///
32 #define EFI_PXE_BASE_CODE_CALLBACK_INTERFACE_REVISION  \
33         EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL_REVISION
34 
35 ///
36 /// UEFI Protocol name.
37 ///
38 typedef struct _EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL;
39 
40 ///
41 /// EFI1.1 Protocol name.
42 ///
43 typedef EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL EFI_PXE_BASE_CODE_CALLBACK;
44 
45 ///
46 /// Event type list for PXE Base Code Protocol function.
47 ///
48 typedef enum {
49   EFI_PXE_BASE_CODE_FUNCTION_FIRST,
50   EFI_PXE_BASE_CODE_FUNCTION_DHCP,
51   EFI_PXE_BASE_CODE_FUNCTION_DISCOVER,
52   EFI_PXE_BASE_CODE_FUNCTION_MTFTP,
53   EFI_PXE_BASE_CODE_FUNCTION_UDP_WRITE,
54   EFI_PXE_BASE_CODE_FUNCTION_UDP_READ,
55   EFI_PXE_BASE_CODE_FUNCTION_ARP,
56   EFI_PXE_BASE_CODE_FUNCTION_IGMP,
57   EFI_PXE_BASE_CODE_PXE_FUNCTION_LAST
58 } EFI_PXE_BASE_CODE_FUNCTION;
59 
60 ///
61 /// Callback status type.
62 ///
63 typedef enum {
64   EFI_PXE_BASE_CODE_CALLBACK_STATUS_FIRST,
65   EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE,
66   EFI_PXE_BASE_CODE_CALLBACK_STATUS_ABORT,
67   EFI_PXE_BASE_CODE_CALLBACK_STATUS_LAST
68 } EFI_PXE_BASE_CODE_CALLBACK_STATUS;
69 
70 /**
71   Callback function that is invoked when the PXE Base Code Protocol is about to transmit, has
72   received, or is waiting to receive a packet.
73 
74   This function is invoked when the PXE Base Code Protocol is about to transmit, has received,
75   or is waiting to receive a packet. Parameters Function and Received specify the type of event.
76   Parameters PacketLen and Packet specify the packet that generated the event. If these fields
77   are zero and NULL respectively, then this is a status update callback. If the operation specified
78   by Function is to continue, then CALLBACK_STATUS_CONTINUE should be returned. If the operation
79   specified by Function should be aborted, then CALLBACK_STATUS_ABORT should be returned. Due to
80   the polling nature of UEFI device drivers, a callback function should not execute for more than 5 ms.
81   The SetParameters() function must be called after a Callback Protocol is installed to enable the
82   use of callbacks.
83 
84   @param  This                  The pointer to the EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL instance.
85   @param  Function              The PXE Base Code Protocol function that is waiting for an event.
86   @param  Received              TRUE if the callback is being invoked due to a receive event. FALSE if
87                                 the callback is being invoked due to a transmit event.
88   @param  PacketLen             The length, in bytes, of Packet. This field will have a value of zero if
89                                 this is a wait for receive event.
90   @param  Packet                If Received is TRUE, a pointer to the packet that was just received;
91                                 otherwise a pointer to the packet that is about to be transmitted.
92 
93   @retval EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE if Function specifies a continue operation
94   @retval EFI_PXE_BASE_CODE_CALLBACK_STATUS_ABORT    if Function specifies an abort operation
95 
96 **/
97 typedef
98 EFI_PXE_BASE_CODE_CALLBACK_STATUS
99 (EFIAPI *EFI_PXE_CALLBACK)(
100   IN EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL  *This,
101   IN EFI_PXE_BASE_CODE_FUNCTION           Function,
102   IN BOOLEAN                              Received,
103   IN UINT32                               PacketLen,
104   IN EFI_PXE_BASE_CODE_PACKET             *Packet     OPTIONAL
105   );
106 
107 ///
108 /// Protocol that is invoked when the PXE Base Code Protocol is about
109 /// to transmit, has received, or is waiting to receive a packet.
110 ///
111 struct _EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL {
112   ///
113   ///  The revision of the EFI_PXE_BASE_CODE_PROTOCOL. All future revisions must
114   ///  be backwards compatible. If a future version is not backwards compatible
115   ///  it is not the same GUID.
116   ///
117   UINT64              Revision;
118   EFI_PXE_CALLBACK    Callback;
119 };
120 
121 extern EFI_GUID  gEfiPxeBaseCodeCallbackProtocolGuid;
122 
123 #endif
124