[apple/xnu.git] / bsd / net / kpi_protocol.h

/*
 * Copyright (c) 2008-2012 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
/*!
	@header kpi_protocol.h
	This header defines an API to interact with protocols in the kernel.
	The KPIs in this header file can be used to interact with protocols
	that already exist in the stack. These KPIs can be used to support
	existing protocols over media types that are not natively supported
	in the kernel, such as ATM.
 */

#ifndef __KPI_PROTOCOL__
#define __KPI_PROTOCOL__
#include <sys/kernel_types.h>
#include <net/kpi_interface.h>

__BEGIN_DECLS

/******************************************************************************/
/* Protocol input/inject                                                      */
/******************************************************************************/

#ifdef BSD_KERNEL_PRIVATE
/*!
	@typedef protocol_input_handler
	@discussion protocol_input_handler is called to input a packet. If
		your protocol has specified a global lock, the lock will be held
		when this funciton is called.
	@pararm protocol The protocol this packet is intended for.
	@param packet The packet that should be input.
 */
typedef void (*proto_input_handler)(protocol_family_t protocol, mbuf_t packet);

/*!
	@typedef proto_input_detached_handler
	@discussion proto_input_detached_handler is called to notify the
		protocol that it has been detached. When this function is
		called, the proto_input_handler will not be called again, making
		it safe to unload.
	@pararm protocol The protocol detached.
 */
typedef void (*proto_input_detached_handler)(protocol_family_t protocol);

/*!
	@function proto_register_input
	@discussion Allows the caller to specify the functions called when a
		packet for a protocol is received.
	@param protocol The protocol family these functions will receive
		packets for.
	@param input The function called when a packet is input.
	@param chains Input function supports packet chains.
	@result A errno error on failure.
 */
extern errno_t proto_register_input(protocol_family_t protocol,
    proto_input_handler input, proto_input_detached_handler detached,
    int chains);

/*!
	@function proto_unregister_input
	@discussion Allows the caller to unregister the input and inject
		functions for a protocol. The input/inject functions may not be
		unregistered immediately if there is a chance they are in use.
		To notify the owner when the functions are no longer in use, the
		proto_detached_handler function will be called. It is not safe
		to unload until the proto_detached_handler is called.
	@param protocol The protocol family these functions will receive
		packets for.
	@param input The function called when a packet is input.
	@param inject The function to called when a packet is injected (not
		on the normal input path).
	@result A errno error on failure.
 */
extern void proto_unregister_input(protocol_family_t protocol);
#endif /* BSD_KERNEL_PRIVATE */

/*!
	@function proto_input
	@discussion Inputs a packet on the specified protocol from the input
		path.
	@param protocol The protocol of the packet.
	@param packet The first packet in a chain of packets to be input.
	@result A errno error on failure. Unless proto_input returns zero,
		the caller is responsible for freeing the mbuf.
 */
extern errno_t proto_input(protocol_family_t protocol, mbuf_t packet);

/*!
	@function proto_inject
	@discussion Injects a packet on the specified protocol from
		anywhere. To avoid recursion, the protocol may need to queue the
		packet to be handled later.
	@param protocol The protocol of the packet.
	@param packet The first packet in a chain of packets to be injected.
	@result A errno error on failure. Unless proto_inject returns zero,
		the caller is responsible for freeing the mbuf.
 */
extern errno_t proto_inject(protocol_family_t protocol, mbuf_t packet);


/******************************************************************************/
/* Protocol plumbing                                                          */
/******************************************************************************/

/*!
	@typedef proto_plumb_handler
	@discussion proto_plumb_handler is called to attach a protocol to an
		interface. A typical protocol plumb function would fill out an
		ifnet_attach_proto_param and call ifnet_attach_protocol.
	@param ifp The interface the protocol should be attached to.
	@param protocol_family The protocol that should be attached to the
		interface.
	@result
		A non-zero value of the attach failed.
 */
typedef errno_t (*proto_plumb_handler)(ifnet_t ifp, protocol_family_t protocol);

/*!
	@typedef proto_unplumb_handler
	@discussion proto_unplumb_handler is called to detach a protocol
		from an interface. A typical unplumb function would call
		ifnet_detach_protocol and perform any necessary cleanup.
	@param ifp The interface the protocol should be detached from.
	@param protocol_family The protocol that should be detached from the
		interface.
 */
typedef void (*proto_unplumb_handler)(ifnet_t ifp, protocol_family_t protocol);

/*!
	@function proto_register_plumber
	@discussion Allows the caller to specify the functions called when a
		protocol is attached to an interface belonging to the specified
		family and when that protocol is detached.
	@param proto_fam The protocol family these plumbing functions will
		handle.
	@param if_fam The interface family these plumbing functions will
		handle.
	@param plumb The function to call to attach the protocol to an
		interface.
	@param unplumb The function to call to detach the protocol to an
		interface, may be NULL in which case ifnet_detach_protocol will
		be used to detach the protocol.
	@result A non-zero value of the attach failed.
 */
extern errno_t proto_register_plumber(protocol_family_t proto_fam,
    ifnet_family_t if_fam, proto_plumb_handler plumb,
    proto_unplumb_handler unplumb);

/*!
	@function proto_unregister_plumber
	@discussion Unregisters a previously registered plumbing function.
	@param proto_fam The protocol family these plumbing functions
		handle.
	@param if_fam The interface family these plumbing functions handle.
 */
extern void proto_unregister_plumber(protocol_family_t proto_fam,
    ifnet_family_t if_fam);

#ifdef BSD_KERNEL_PRIVATE
/*
	@function proto_plumb
	@discussion Plumbs a protocol to an actual interface.  This will find
		a registered protocol module and call its attach function.
		The module will typically call dlil_attach_protocol() with the
		appropriate parameters.
	@param protocol_family The protocol family.
	@param ifp The interface to plumb the protocol to.
	@result 0: No error.
		ENOENT: No module was registered.
		Other: Error returned by the attach_proto function
*/
extern errno_t proto_plumb(protocol_family_t protocol_family, ifnet_t ifp);

/*
	@function proto_unplumb
	@discussion Unplumbs a protocol from an interface.  This will find
		a registered protocol module and call its detach function.
		The module will typically call dlil_detach_protocol() with
		the appropriate parameters.  If no module is found, this
		function will call dlil_detach_protocol directly().
	@param protocol_family The protocol family.
	@param ifp The interface to unplumb the protocol from.
	@result 0: No error.
		ENOENT: No module was registered.
		Other: Error returned by the attach_proto function
*/
extern errno_t proto_unplumb(protocol_family_t protocol_family, ifnet_t ifp);

__private_extern__ void
proto_kpi_init(void);

#endif /* BSD_KERNEL_PRIVATE */
__END_DECLS

#endif /* __KPI_PROTOCOL__ */
Commit	Line	Data
91447636	1	/*
39236c6e	2	* Copyright (c) 2008-2012 Apple Inc. All rights reserved.
5d5c5d0d	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
39236c6e	5	*
2d21ac55 A	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.
39236c6e	14	*
2d21ac55 A	15	* Please obtain a copy of the License at
2d21ac55 A	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
39236c6e	17	*
2d21ac55 A	18	* The Original Code and all software distributed under the License are
2d21ac55 A	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	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.
39236c6e	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
91447636 A	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
91447636 A	42	__BEGIN_DECLS
91447636 A	43
b0d623f7 A	44	/******************************************************************************/
	45	/* Protocol input/inject */
	46	/******************************************************************************/
91447636	47
39236c6e	48	#ifdef BSD_KERNEL_PRIVATE
91447636 A	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.
2d21ac55	76	@param chains Input function supports packet chains.
91447636 A	77	@result A errno error on failure.
91447636 A	78	*/
b0d623f7 A	79	extern errno_t proto_register_input(protocol_family_t protocol,
	80	proto_input_handler input, proto_input_detached_handler detached,
	81	int chains);
91447636 A	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	@param input The function called when a packet is input.
	94	@param inject The function to called when a packet is injected (not
	95	on the normal input path).
	96	@result A errno error on failure.
	97	*/
b0d623f7	98	extern void proto_unregister_input(protocol_family_t protocol);
39236c6e	99	#endif /* BSD_KERNEL_PRIVATE */
91447636 A	100
	101	/*!
	102	@function proto_input
	103	@discussion Inputs a packet on the specified protocol from the input
	104	path.
	105	@param protocol The protocol of the packet.
	106	@param packet The first packet in a chain of packets to be input.
	107	@result A errno error on failure. Unless proto_input returns zero,
	108	the caller is responsible for freeing the mbuf.
	109	*/
b0d623f7	110	extern errno_t proto_input(protocol_family_t protocol, mbuf_t packet);
91447636 A	111
	112	/*!
	113	@function proto_inject
	114	@discussion Injects a packet on the specified protocol from
	115	anywhere. To avoid recursion, the protocol may need to queue the
	116	packet to be handled later.
	117	@param protocol The protocol of the packet.
	118	@param packet The first packet in a chain of packets to be injected.
	119	@result A errno error on failure. Unless proto_inject returns zero,
	120	the caller is responsible for freeing the mbuf.
	121	*/
b0d623f7	122	extern errno_t proto_inject(protocol_family_t protocol, mbuf_t packet);
91447636 A	123
91447636 A	124
b0d623f7 A	125	/******************************************************************************/
	126	/* Protocol plumbing */
	127	/******************************************************************************/
91447636 A	128
	129	/*!
	130	@typedef proto_plumb_handler
	131	@discussion proto_plumb_handler is called to attach a protocol to an
	132	interface. A typical protocol plumb function would fill out an
	133	ifnet_attach_proto_param and call ifnet_attach_protocol.
	134	@param ifp The interface the protocol should be attached to.
	135	@param protocol_family The protocol that should be attached to the
	136	interface.
	137	@result
	138	A non-zero value of the attach failed.
	139	*/
	140	typedef errno_t (*proto_plumb_handler)(ifnet_t ifp, protocol_family_t protocol);
	141
	142	/*!
	143	@typedef proto_unplumb_handler
	144	@discussion proto_unplumb_handler is called to detach a protocol
	145	from an interface. A typical unplumb function would call
	146	ifnet_detach_protocol and perform any necessary cleanup.
	147	@param ifp The interface the protocol should be detached from.
	148	@param protocol_family The protocol that should be detached from the
	149	interface.
	150	*/
	151	typedef void (*proto_unplumb_handler)(ifnet_t ifp, protocol_family_t protocol);
	152
	153	/*!
	154	@function proto_register_plumber
b0d623f7 A	155	@discussion Allows the caller to specify the functions called when a
	156	protocol is attached to an interface belonging to the specified
	157	family and when that protocol is detached.
91447636 A	158	@param proto_fam The protocol family these plumbing functions will
	159	handle.
	160	@param if_fam The interface family these plumbing functions will
	161	handle.
	162	@param plumb The function to call to attach the protocol to an
	163	interface.
	164	@param unplumb The function to call to detach the protocol to an
	165	interface, may be NULL in which case ifnet_detach_protocol will
	166	be used to detach the protocol.
	167	@result A non-zero value of the attach failed.
	168	*/
b0d623f7 A	169	extern errno_t proto_register_plumber(protocol_family_t proto_fam,
	170	ifnet_family_t if_fam, proto_plumb_handler plumb,
	171	proto_unplumb_handler unplumb);
91447636 A	172
	173	/*!
	174	@function proto_unregister_plumber
	175	@discussion Unregisters a previously registered plumbing function.
	176	@param proto_fam The protocol family these plumbing functions
	177	handle.
	178	@param if_fam The interface family these plumbing functions handle.
	179	*/
b0d623f7 A	180	extern void proto_unregister_plumber(protocol_family_t proto_fam,
b0d623f7 A	181	ifnet_family_t if_fam);
91447636	182
39236c6e	183	#ifdef BSD_KERNEL_PRIVATE
b0d623f7 A	184	/*
	185	@function proto_plumb
	186	@discussion Plumbs a protocol to an actual interface. This will find
	187	a registered protocol module and call its attach function.
	188	The module will typically call dlil_attach_protocol() with the
	189	appropriate parameters.
	190	@param protocol_family The protocol family.
	191	@param ifp The interface to plumb the protocol to.
	192	@result 0: No error.
	193	ENOENT: No module was registered.
	194	Other: Error returned by the attach_proto function
2d21ac55	195	*/
b0d623f7	196	extern errno_t proto_plumb(protocol_family_t protocol_family, ifnet_t ifp);
2d21ac55	197
b0d623f7 A	198	/*
	199	@function proto_unplumb
	200	@discussion Unplumbs a protocol from an interface. This will find
	201	a registered protocol module and call its detach function.
	202	The module will typically call dlil_detach_protocol() with
	203	the appropriate parameters. If no module is found, this
	204	function will call dlil_detach_protocol directly().
	205	@param protocol_family The protocol family.
	206	@param ifp The interface to unplumb the protocol from.
	207	@result 0: No error.
	208	ENOENT: No module was registered.
	209	Other: Error returned by the attach_proto function
2d21ac55	210	*/
b0d623f7	211	extern errno_t proto_unplumb(protocol_family_t protocol_family, ifnet_t ifp);
2d21ac55	212
b0d623f7	213	__private_extern__ void
39236c6e	214	proto_kpi_init(void);
2d21ac55	215
39236c6e	216	#endif /* BSD_KERNEL_PRIVATE */
91447636	217	__END_DECLS
6601e61a	218
b0d623f7	219	#endif /* __KPI_PROTOCOL__ */