1 | /* |
2 | * Copyright (c) 2008-2016 Apple Inc. All rights reserved. |
3 | * |
4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
5 | * |
6 | * This file contains Original Code and/or Modifications of Original Code |
7 | * as defined in and that are subject to the Apple Public Source License |
8 | * Version 2.0 (the 'License'). You may not use this file except in |
9 | * compliance with the License. The rights granted to you under the License |
10 | * may not be used to create, or enable the creation or redistribution of, |
11 | * unlawful or unlicensed copies of an Apple operating system, or to |
12 | * circumvent, violate, or enable the circumvention or violation of, any |
13 | * terms of an Apple operating system software license agreement. |
14 | * |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. |
17 | * |
18 | * The Original Code and all software distributed under the License are |
19 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, |
22 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
23 | * Please see the License for the specific language governing rights and |
24 | * limitations under the License. |
25 | * |
26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
27 | */ |
28 | /*! |
29 | * @header kpi_protocol.h |
30 | * This header defines an API to interact with protocols in the kernel. |
31 | * The KPIs in this header file can be used to interact with protocols |
32 | * that already exist in the stack. These KPIs can be used to support |
33 | * existing protocols over media types that are not natively supported |
34 | * in the kernel, such as ATM. |
35 | */ |
36 | |
37 | #ifndef __KPI_PROTOCOL__ |
38 | #define __KPI_PROTOCOL__ |
39 | #include <sys/kernel_types.h> |
40 | #include <net/kpi_interface.h> |
41 | |
42 | #ifndef PRIVATE |
43 | #include <Availability.h> |
44 | #define __NKE_API_DEPRECATED __API_DEPRECATED("Network Kernel Extension KPI is deprecated", macos(10.4, 10.15.4)) |
45 | #else |
46 | #define __NKE_API_DEPRECATED |
47 | #endif /* PRIVATE */ |
48 | |
49 | __BEGIN_DECLS |
50 | |
51 | /******************************************************************************/ |
52 | /* Protocol input/inject */ |
53 | /******************************************************************************/ |
54 | |
55 | #ifdef BSD_KERNEL_PRIVATE |
56 | /*! |
57 | * @typedef protocol_input_handler |
58 | * @discussion protocol_input_handler is called to input a packet. If |
59 | * your protocol has specified a global lock, the lock will be held |
60 | * when this funciton is called. |
61 | * @pararm protocol The protocol this packet is intended for. |
62 | * @param packet The packet that should be input. |
63 | */ |
64 | typedef void (*proto_input_handler)(protocol_family_t protocol, mbuf_t packet); |
65 | |
66 | /*! |
67 | * @typedef proto_input_detached_handler |
68 | * @discussion proto_input_detached_handler is called to notify the |
69 | * protocol that it has been detached. When this function is |
70 | * called, the proto_input_handler will not be called again, making |
71 | * it safe to unload. |
72 | * @pararm protocol The protocol detached. |
73 | */ |
74 | typedef void (*proto_input_detached_handler)(protocol_family_t protocol); |
75 | |
76 | /*! |
77 | * @function proto_register_input |
78 | * @discussion Allows the caller to specify the functions called when a |
79 | * packet for a protocol is received. |
80 | * @param protocol The protocol family these functions will receive |
81 | * packets for. |
82 | * @param input The function called when a packet is input. |
83 | * @param chains Input function supports packet chains. |
84 | * @result A errno error on failure. |
85 | */ |
86 | extern errno_t proto_register_input(protocol_family_t protocol, |
87 | proto_input_handler input, proto_input_detached_handler detached, |
88 | int chains); |
89 | |
90 | /*! |
91 | * @function proto_unregister_input |
92 | * @discussion Allows the caller to unregister the input and inject |
93 | * functions for a protocol. The input/inject functions may not be |
94 | * unregistered immediately if there is a chance they are in use. |
95 | * To notify the owner when the functions are no longer in use, the |
96 | * proto_detached_handler function will be called. It is not safe |
97 | * to unload until the proto_detached_handler is called. |
98 | * @param protocol The protocol family these functions will receive |
99 | * packets for. |
100 | */ |
101 | extern void proto_unregister_input(protocol_family_t protocol); |
102 | #endif /* BSD_KERNEL_PRIVATE */ |
103 | |
104 | /*! |
105 | * @function proto_input |
106 | * @discussion Inputs a packet on the specified protocol from the input |
107 | * path. |
108 | * @param protocol The protocol of the packet. |
109 | * @param packet The first packet in a chain of packets to be input. |
110 | * @result A errno error on failure. Unless proto_input returns zero, |
111 | * the caller is responsible for freeing the mbuf. |
112 | */ |
113 | extern errno_t proto_input(protocol_family_t protocol, mbuf_t packet) |
114 | __NKE_API_DEPRECATED; |
115 | |
116 | /*! |
117 | * @function proto_inject |
118 | * @discussion Injects a packet on the specified protocol from |
119 | * anywhere. To avoid recursion, the protocol may need to queue the |
120 | * packet to be handled later. |
121 | * @param protocol The protocol of the packet. |
122 | * @param packet The first packet in a chain of packets to be injected. |
123 | * @result A errno error on failure. Unless proto_inject returns zero, |
124 | * the caller is responsible for freeing the mbuf. |
125 | */ |
126 | extern errno_t proto_inject(protocol_family_t protocol, mbuf_t packet) |
127 | __NKE_API_DEPRECATED; |
128 | |
129 | |
130 | /******************************************************************************/ |
131 | /* Protocol plumbing */ |
132 | /******************************************************************************/ |
133 | |
134 | /*! |
135 | * @typedef proto_plumb_handler |
136 | * @discussion proto_plumb_handler is called to attach a protocol to an |
137 | * interface. A typical protocol plumb function would fill out an |
138 | * ifnet_attach_proto_param and call ifnet_attach_protocol. |
139 | * @param ifp The interface the protocol should be attached to. |
140 | * @param protocol The protocol that should be attached to the |
141 | * interface. |
142 | * @result |
143 | * A non-zero value of the attach failed. |
144 | */ |
145 | typedef errno_t (*proto_plumb_handler)(ifnet_t ifp, protocol_family_t protocol); |
146 | |
147 | /*! |
148 | * @typedef proto_unplumb_handler |
149 | * @discussion proto_unplumb_handler is called to detach a protocol |
150 | * from an interface. A typical unplumb function would call |
151 | * ifnet_detach_protocol and perform any necessary cleanup. |
152 | * @param ifp The interface the protocol should be detached from. |
153 | * @param protocol The protocol that should be detached from the |
154 | * interface. |
155 | */ |
156 | typedef void (*proto_unplumb_handler)(ifnet_t ifp, protocol_family_t protocol); |
157 | |
158 | /*! |
159 | * @function proto_register_plumber |
160 | * @discussion Allows the caller to specify the functions called when a |
161 | * protocol is attached to an interface belonging to the specified |
162 | * family and when that protocol is detached. |
163 | * @param proto_fam The protocol family these plumbing functions will |
164 | * handle. |
165 | * @param if_fam The interface family these plumbing functions will |
166 | * handle. |
167 | * @param plumb The function to call to attach the protocol to an |
168 | * interface. |
169 | * @param unplumb The function to call to detach the protocol to an |
170 | * interface, may be NULL in which case ifnet_detach_protocol will |
171 | * be used to detach the protocol. |
172 | * @result A non-zero value of the attach failed. |
173 | */ |
174 | extern errno_t proto_register_plumber(protocol_family_t proto_fam, |
175 | ifnet_family_t if_fam, proto_plumb_handler plumb, |
176 | proto_unplumb_handler unplumb) |
177 | __NKE_API_DEPRECATED; |
178 | |
179 | /*! |
180 | * @function proto_unregister_plumber |
181 | * @discussion Unregisters a previously registered plumbing function. |
182 | * @param proto_fam The protocol family these plumbing functions |
183 | * handle. |
184 | * @param if_fam The interface family these plumbing functions handle. |
185 | */ |
186 | extern void proto_unregister_plumber(protocol_family_t proto_fam, |
187 | ifnet_family_t if_fam) |
188 | __NKE_API_DEPRECATED; |
189 | |
190 | #ifdef BSD_KERNEL_PRIVATE |
191 | /* |
192 | * @function proto_plumb |
193 | * @discussion Plumbs a protocol to an actual interface. This will find |
194 | * a registered protocol module and call its attach function. |
195 | * The module will typically call dlil_attach_protocol() with the |
196 | * appropriate parameters. |
197 | * @param protocol_family The protocol family. |
198 | * @param ifp The interface to plumb the protocol to. |
199 | * @result 0: No error. |
200 | * ENOENT: No module was registered. |
201 | * Other: Error returned by the attach_proto function |
202 | */ |
203 | extern errno_t proto_plumb(protocol_family_t protocol_family, ifnet_t ifp); |
204 | |
205 | /* |
206 | * @function proto_unplumb |
207 | * @discussion Unplumbs a protocol from an interface. This will find |
208 | * a registered protocol module and call its detach function. |
209 | * The module will typically call dlil_detach_protocol() with |
210 | * the appropriate parameters. If no module is found, this |
211 | * function will call dlil_detach_protocol directly(). |
212 | * @param protocol_family The protocol family. |
213 | * @param ifp The interface to unplumb the protocol from. |
214 | * @result 0: No error. |
215 | * ENOENT: No module was registered. |
216 | * Other: Error returned by the attach_proto function |
217 | */ |
218 | extern errno_t proto_unplumb(protocol_family_t protocol_family, ifnet_t ifp); |
219 | |
220 | __private_extern__ void |
221 | proto_kpi_init(void); |
222 | |
223 | #endif /* BSD_KERNEL_PRIVATE */ |
224 | __END_DECLS |
225 | |
226 | #undef __NKE_API_DEPRECATED |
227 | #endif /* __KPI_PROTOCOL__ */ |
228 | |