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