bsd/net/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 __BEGIN_DECLS
  43
  44 /******************************************************************************/
  45 /* Protocol input/inject                                                      */
  46 /******************************************************************************/
  47
  48 #ifdef BSD_KERNEL_PRIVATE
  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.
  76  *       @param chains Input function supports packet chains.
  77  *       @result A errno error on failure.
  78  */
  79 extern errno_t proto_register_input(protocol_family_t protocol,
  80     proto_input_handler input, proto_input_detached_handler detached,
  81     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  */
  94 extern void proto_unregister_input(protocol_family_t protocol);
  95 #endif /* BSD_KERNEL_PRIVATE */
  96
  97 /*!
  98  *       @function proto_input
  99  *       @discussion Inputs a packet on the specified protocol from the input
 100  *               path.
 101  *       @param protocol The protocol of the packet.
 102  *       @param packet The first packet in a chain of packets to be input.
 103  *       @result A errno error on failure. Unless proto_input returns zero,
 104  *               the caller is responsible for freeing the mbuf.
 105  */
 106 extern errno_t proto_input(protocol_family_t protocol, mbuf_t packet);
 107
 108 /*!
 109  *       @function proto_inject
 110  *       @discussion Injects a packet on the specified protocol from
 111  *               anywhere. To avoid recursion, the protocol may need to queue the
 112  *               packet to be handled later.
 113  *       @param protocol The protocol of the packet.
 114  *       @param packet The first packet in a chain of packets to be injected.
 115  *       @result A errno error on failure. Unless proto_inject returns zero,
 116  *               the caller is responsible for freeing the mbuf.
 117  */
 118 extern errno_t proto_inject(protocol_family_t protocol, mbuf_t packet);
 119
 120
 121 /******************************************************************************/
 122 /* Protocol plumbing                                                          */
 123 /******************************************************************************/
 124
 125 /*!
 126  *       @typedef proto_plumb_handler
 127  *       @discussion proto_plumb_handler is called to attach a protocol to an
 128  *               interface. A typical protocol plumb function would fill out an
 129  *               ifnet_attach_proto_param and call ifnet_attach_protocol.
 130  *       @param ifp The interface the protocol should be attached to.
 131  *       @param protocol The protocol that should be attached to the
 132  *               interface.
 133  *       @result
 134  *               A non-zero value of the attach failed.
 135  */
 136 typedef errno_t (*proto_plumb_handler)(ifnet_t ifp, protocol_family_t protocol);
 137
 138 /*!
 139  *       @typedef proto_unplumb_handler
 140  *       @discussion proto_unplumb_handler is called to detach a protocol
 141  *               from an interface. A typical unplumb function would call
 142  *               ifnet_detach_protocol and perform any necessary cleanup.
 143  *       @param ifp The interface the protocol should be detached from.
 144  *       @param protocol The protocol that should be detached from the
 145  *               interface.
 146  */
 147 typedef void (*proto_unplumb_handler)(ifnet_t ifp, protocol_family_t protocol);
 148
 149 /*!
 150  *       @function proto_register_plumber
 151  *       @discussion Allows the caller to specify the functions called when a
 152  *               protocol is attached to an interface belonging to the specified
 153  *               family and when that protocol is detached.
 154  *       @param proto_fam The protocol family these plumbing functions will
 155  *               handle.
 156  *       @param if_fam The interface family these plumbing functions will
 157  *               handle.
 158  *       @param plumb The function to call to attach the protocol to an
 159  *               interface.
 160  *       @param unplumb The function to call to detach the protocol to an
 161  *               interface, may be NULL in which case ifnet_detach_protocol will
 162  *               be used to detach the protocol.
 163  *       @result A non-zero value of the attach failed.
 164  */
 165 extern errno_t proto_register_plumber(protocol_family_t proto_fam,
 166     ifnet_family_t if_fam, proto_plumb_handler plumb,
 167     proto_unplumb_handler unplumb);
 168
 169 /*!
 170  *       @function proto_unregister_plumber
 171  *       @discussion Unregisters a previously registered plumbing function.
 172  *       @param proto_fam The protocol family these plumbing functions
 173  *               handle.
 174  *       @param if_fam The interface family these plumbing functions handle.
 175  */
 176 extern void proto_unregister_plumber(protocol_family_t proto_fam,
 177     ifnet_family_t if_fam);
 178
 179 #ifdef BSD_KERNEL_PRIVATE
 180 /*
 181  *       @function proto_plumb
 182  *       @discussion Plumbs a protocol to an actual interface.  This will find
 183  *               a registered protocol module and call its attach function.
 184  *               The module will typically call dlil_attach_protocol() with the
 185  *               appropriate parameters.
 186  *       @param protocol_family The protocol family.
 187  *       @param ifp The interface to plumb the protocol to.
 188  *       @result 0: No error.
 189  *               ENOENT: No module was registered.
 190  *               Other: Error returned by the attach_proto function
 191  */
 192 extern errno_t proto_plumb(protocol_family_t protocol_family, ifnet_t ifp);
 193
 194 /*
 195  *       @function proto_unplumb
 196  *       @discussion Unplumbs a protocol from an interface.  This will find
 197  *               a registered protocol module and call its detach function.
 198  *               The module will typically call dlil_detach_protocol() with
 199  *               the appropriate parameters.  If no module is found, this
 200  *               function will call dlil_detach_protocol directly().
 201  *       @param protocol_family The protocol family.
 202  *       @param ifp The interface to unplumb the protocol from.
 203  *       @result 0: No error.
 204  *               ENOENT: No module was registered.
 205  *               Other: Error returned by the attach_proto function
 206  */
 207 extern errno_t proto_unplumb(protocol_family_t protocol_family, ifnet_t ifp);
 208
 209 __private_extern__ void
 210 proto_kpi_init(void);
 211
 212 #endif /* BSD_KERNEL_PRIVATE */
 213 __END_DECLS
 214
 215 #endif /* __KPI_PROTOCOL__ */