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