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 | __BEGIN_DECLS |
43 | |
44 | /******************************************************************************/ |
45 | /* Protocol input/inject */ |
46 | /******************************************************************************/ |
47 | |
48 | #ifdef BSD_KERNEL_PRIVATE |
49 | /*! |
50 | @typedef protocol_input_handler |
51 | @discussion protocol_input_handler is called to input a packet. If |
52 | your protocol has specified a global lock, the lock will be held |
53 | when this funciton is called. |
54 | @pararm protocol The protocol this packet is intended for. |
55 | @param packet The packet that should be input. |
56 | */ |
57 | typedef void (*proto_input_handler)(protocol_family_t protocol, mbuf_t packet); |
58 | |
59 | /*! |
60 | @typedef proto_input_detached_handler |
61 | @discussion proto_input_detached_handler is called to notify the |
62 | protocol that it has been detached. When this function is |
63 | called, the proto_input_handler will not be called again, making |
64 | it safe to unload. |
65 | @pararm protocol The protocol detached. |
66 | */ |
67 | typedef void (*proto_input_detached_handler)(protocol_family_t protocol); |
68 | |
69 | /*! |
70 | @function proto_register_input |
71 | @discussion Allows the caller to specify the functions called when a |
72 | packet for a protocol is received. |
73 | @param protocol The protocol family these functions will receive |
74 | packets for. |
75 | @param input The function called when a packet is input. |
76 | @param chains Input function supports packet chains. |
77 | @result A errno error on failure. |
78 | */ |
79 | extern errno_t proto_register_input(protocol_family_t protocol, |
80 | proto_input_handler input, proto_input_detached_handler detached, |
81 | int chains); |
82 | |
83 | /*! |
84 | @function proto_unregister_input |
85 | @discussion Allows the caller to unregister the input and inject |
86 | functions for a protocol. The input/inject functions may not be |
87 | unregistered immediately if there is a chance they are in use. |
88 | To notify the owner when the functions are no longer in use, the |
89 | proto_detached_handler function will be called. It is not safe |
90 | to unload until the proto_detached_handler is called. |
91 | @param protocol The protocol family these functions will receive |
92 | packets for. |
93 | */ |
94 | extern void proto_unregister_input(protocol_family_t protocol); |
95 | #endif /* BSD_KERNEL_PRIVATE */ |
96 | |
97 | /*! |
98 | @function proto_input |
99 | @discussion Inputs a packet on the specified protocol from the input |
100 | path. |
101 | @param protocol The protocol of the packet. |
102 | @param packet The first packet in a chain of packets to be input. |
103 | @result A errno error on failure. Unless proto_input returns zero, |
104 | the caller is responsible for freeing the mbuf. |
105 | */ |
106 | extern errno_t proto_input(protocol_family_t protocol, mbuf_t packet); |
107 | |
108 | /*! |
109 | @function proto_inject |
110 | @discussion Injects a packet on the specified protocol from |
111 | anywhere. To avoid recursion, the protocol may need to queue the |
112 | packet to be handled later. |
113 | @param protocol The protocol of the packet. |
114 | @param packet The first packet in a chain of packets to be injected. |
115 | @result A errno error on failure. Unless proto_inject returns zero, |
116 | the caller is responsible for freeing the mbuf. |
117 | */ |
118 | extern errno_t proto_inject(protocol_family_t protocol, mbuf_t packet); |
119 | |
120 | |
121 | /******************************************************************************/ |
122 | /* Protocol plumbing */ |
123 | /******************************************************************************/ |
124 | |
125 | /*! |
126 | @typedef proto_plumb_handler |
127 | @discussion proto_plumb_handler is called to attach a protocol to an |
128 | interface. A typical protocol plumb function would fill out an |
129 | ifnet_attach_proto_param and call ifnet_attach_protocol. |
130 | @param ifp The interface the protocol should be attached to. |
131 | @param protocol The protocol that should be attached to the |
132 | interface. |
133 | @result |
134 | A non-zero value of the attach failed. |
135 | */ |
136 | typedef errno_t (*proto_plumb_handler)(ifnet_t ifp, protocol_family_t protocol); |
137 | |
138 | /*! |
139 | @typedef proto_unplumb_handler |
140 | @discussion proto_unplumb_handler is called to detach a protocol |
141 | from an interface. A typical unplumb function would call |
142 | ifnet_detach_protocol and perform any necessary cleanup. |
143 | @param ifp The interface the protocol should be detached from. |
144 | @param protocol The protocol that should be detached from the |
145 | interface. |
146 | */ |
147 | typedef void (*proto_unplumb_handler)(ifnet_t ifp, protocol_family_t protocol); |
148 | |
149 | /*! |
150 | @function proto_register_plumber |
151 | @discussion Allows the caller to specify the functions called when a |
152 | protocol is attached to an interface belonging to the specified |
153 | family and when that protocol is detached. |
154 | @param proto_fam The protocol family these plumbing functions will |
155 | handle. |
156 | @param if_fam The interface family these plumbing functions will |
157 | handle. |
158 | @param plumb The function to call to attach the protocol to an |
159 | interface. |
160 | @param unplumb The function to call to detach the protocol to an |
161 | interface, may be NULL in which case ifnet_detach_protocol will |
162 | be used to detach the protocol. |
163 | @result A non-zero value of the attach failed. |
164 | */ |
165 | extern errno_t proto_register_plumber(protocol_family_t proto_fam, |
166 | ifnet_family_t if_fam, proto_plumb_handler plumb, |
167 | proto_unplumb_handler unplumb); |
168 | |
169 | /*! |
170 | @function proto_unregister_plumber |
171 | @discussion Unregisters a previously registered plumbing function. |
172 | @param proto_fam The protocol family these plumbing functions |
173 | handle. |
174 | @param if_fam The interface family these plumbing functions handle. |
175 | */ |
176 | extern void proto_unregister_plumber(protocol_family_t proto_fam, |
177 | ifnet_family_t if_fam); |
178 | |
179 | #ifdef BSD_KERNEL_PRIVATE |
180 | /* |
181 | @function proto_plumb |
182 | @discussion Plumbs a protocol to an actual interface. This will find |
183 | a registered protocol module and call its attach function. |
184 | The module will typically call dlil_attach_protocol() with the |
185 | appropriate parameters. |
186 | @param protocol_family The protocol family. |
187 | @param ifp The interface to plumb the protocol to. |
188 | @result 0: No error. |
189 | ENOENT: No module was registered. |
190 | Other: Error returned by the attach_proto function |
191 | */ |
192 | extern errno_t proto_plumb(protocol_family_t protocol_family, ifnet_t ifp); |
193 | |
194 | /* |
195 | @function proto_unplumb |
196 | @discussion Unplumbs a protocol from an interface. This will find |
197 | a registered protocol module and call its detach function. |
198 | The module will typically call dlil_detach_protocol() with |
199 | the appropriate parameters. If no module is found, this |
200 | function will call dlil_detach_protocol directly(). |
201 | @param protocol_family The protocol family. |
202 | @param ifp The interface to unplumb the protocol from. |
203 | @result 0: No error. |
204 | ENOENT: No module was registered. |
205 | Other: Error returned by the attach_proto function |
206 | */ |
207 | extern errno_t proto_unplumb(protocol_family_t protocol_family, ifnet_t ifp); |
208 | |
209 | __private_extern__ void |
210 | proto_kpi_init(void); |
211 | |
212 | #endif /* BSD_KERNEL_PRIVATE */ |
213 | __END_DECLS |
214 | |
215 | #endif /* __KPI_PROTOCOL__ */ |
216 | |