bsd/net/kpi_protocol.h

   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  */
  58 typedef 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  */
  68 typedef 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  */
  80 errno_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  */
  98 void    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  */
 110 errno_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  */
 122 errno_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  */
 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
 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  */
 169 errno_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  */
 179 void    proto_unregister_plumber(protocol_family_t proto_fam, ifnet_family_t if_fam);
 180
 181 #ifdef KERNEL_PRIVATE
 182
 183 /*
 184
 185 Function : 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
 191 Parameters :
 192     'protocol_family' is PF_INET, PF_INET6, ...
 193     'ifp' is the interface to plumb the protocol to.
 194
 195 Return code :
 196
 197 0 :
 198
 199     No error.
 200
 201 ENOENT:
 202
 203     No module was registered.
 204
 205 other:
 206
 207     Error returned by the attach_proto function
 208
 209 */
 210 errno_t proto_plumb(protocol_family_t protocol_family, ifnet_t ifp);
 211
 212 /*
 213
 214 Function : 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
 221 Parameters :
 222     'protocol_family' is PF_INET, PF_INET6, ...
 223     'ifp' is APPLE_IF_FAM_ETHERNET, APPLE_IF_FAM_PPP, ...
 224
 225 Return code :
 226
 227 0 :
 228
 229     No error.
 230
 231 ENOENT:
 232
 233     No module was registered.
 234
 235 other:
 236
 237     Error returned by the attach_proto function
 238
 239 */
 240 errno_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