1/* 2 * Copyright (c) 2004 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 */ 80errno_t proto_register_input(protocol_family_t protocol, proto_input_handler input, 81 proto_input_detached_handler detached, 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 @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 */ 98void proto_unregister_input(protocol_family_t protocol); 99#endif 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 */ 110errno_t proto_input(protocol_family_t protocol, mbuf_t packet); 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 */ 122errno_t proto_inject(protocol_family_t protocol, mbuf_t packet); 123 124 125/****************************************************************************/ 126/* Protocol plumbing */ 127/****************************************************************************/ 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 */ 140typedef 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 */ 151typedef void (*proto_unplumb_handler)(ifnet_t ifp, protocol_family_t protocol); 152 153/*! 154 @function proto_register_plumber 155 @discussion Allows the caller to specify the functions called when a protocol 156 is attached to an interface belonging to the specified family and when 157 that protocol is detached. 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 */ 169errno_t proto_register_plumber(protocol_family_t proto_fam, ifnet_family_t if_fam, 170 proto_plumb_handler plumb, proto_unplumb_handler unplumb); 171 172/*! 173 @function proto_unregister_plumber 174 @discussion Unregisters a previously registered plumbing function. 175 @param proto_fam The protocol family these plumbing functions 176 handle. 177 @param if_fam The interface family these plumbing functions handle. 178 */ 179void proto_unregister_plumber(protocol_family_t proto_fam, ifnet_family_t if_fam); 180 181#ifdef KERNEL_PRIVATE 182 183/* 184 185Function : proto_plumb 186 187 proto_plumb() will plumb a protocol to an actual interface. 188 This will find a registered protocol module and call its attach function. 189 The module will typically call dlil_attach_protocol with the appropriate parameters. 190 191Parameters : 192 'protocol_family' is PF_INET, PF_INET6, ... 193 'ifp' is the interface to plumb the protocol to. 194 195Return code : 196 1970 : 198 199 No error. 200 201ENOENT: 202 203 No module was registered. 204 205other: 206 207 Error returned by the attach_proto function 208 209*/ 210errno_t proto_plumb(protocol_family_t protocol_family, ifnet_t ifp); 211 212/* 213 214Function : proto_unplumb 215 216 proto_unplumb() will unplumb a protocol from an interface. 217 This will find a registered protocol module and call its detach function. 218 The module will typically call dlil_detach_protocol with the appropriate parameters. 219 If no module is found, this function will call dlil_detach_protocol directly. 220 221Parameters : 222 'protocol_family' is PF_INET, PF_INET6, ... 223 'ifp' is APPLE_IF_FAM_ETHERNET, APPLE_IF_FAM_PPP, ... 224 225Return code : 226 2270 : 228 229 No error. 230 231ENOENT: 232 233 No module was registered. 234 235other: 236 237 Error returned by the attach_proto function 238 239*/ 240errno_t proto_unplumb(protocol_family_t protocol_family, ifnet_t ifp); 241 242__private_extern__ void proto_kpi_init(void) __attribute__((section("__TEXT, initcode"))); 243 244#endif KERNEL_PRIVATE 245__END_DECLS 246 247#endif 248