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 */
64typedef 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 */
74typedef 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 */
86extern 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 */
101extern 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 */
113extern 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 */
126extern 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 */
145typedef 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 */
156typedef 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 */
174extern 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 */
186extern 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 */
203extern 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 */
218extern errno_t proto_unplumb(protocol_family_t protocol_family, ifnet_t ifp);
219
220__private_extern__ void
221proto_kpi_init(void);
222
223#endif /* BSD_KERNEL_PRIVATE */
224__END_DECLS
225
226#undef __NKE_API_DEPRECATED
227#endif /* __KPI_PROTOCOL__ */
228