bsd/net/kpi_protocol.h

   1 /*
   2  * Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*!
  23         @header kpi_protocol.h
  24         This header defines an API to interact with protocols in the kernel.
  25         The KPIs in this header file can be used to interact with protocols
  26         that already exist in the stack. These KPIs can be used to support
  27         existing protocols over media types that are not natively supported
  28         in the kernel, such as ATM.
  29  */
  30
  31 #ifndef __KPI_PROTOCOL__
  32 #define __KPI_PROTOCOL__
  33 #include <sys/kernel_types.h>
  34 #include <net/kpi_interface.h>
  35
  36
  37 __BEGIN_DECLS
  38
  39 /****************************************************************************/
  40 /* Protocol input/inject                                                                                                        */
  41 /****************************************************************************/
  42
  43 #ifdef KERNEL_PRIVATE
  44 /*!
  45         @typedef protocol_input_handler
  46         @discussion protocol_input_handler is called to input a packet. If
  47                 your protocol has specified a global lock, the lock will be held
  48                 when this funciton is called.
  49         @pararm protocol The protocol this packet is intended for.
  50         @param packet The packet that should be input.
  51  */
  52 typedef void (*proto_input_handler)(protocol_family_t protocol, mbuf_t packet);
  53
  54 /*!
  55         @typedef proto_input_detached_handler
  56         @discussion proto_input_detached_handler is called to notify the
  57                 protocol that it has been detached. When this function is
  58                 called, the proto_input_handler will not be called again, making
  59                 it safe to unload.
  60         @pararm protocol The protocol detached.
  61  */
  62 typedef void (*proto_input_detached_handler)(protocol_family_t protocol);
  63
  64 /*!
  65         @function proto_register_input
  66         @discussion Allows the caller to specify the functions called when a
  67                 packet for a protocol is received.
  68         @param protocol The protocol family these functions will receive
  69                 packets for.
  70         @param input The function called when a packet is input.
  71         @result A errno error on failure.
  72  */
  73 errno_t proto_register_input(protocol_family_t protocol, proto_input_handler input,
  74                                                          proto_input_detached_handler detached);
  75
  76 /*!
  77         @function proto_unregister_input
  78         @discussion Allows the caller to unregister the input and inject
  79                 functions for a protocol. The input/inject functions may not be
  80                 unregistered immediately if there is a chance they are in use.
  81                 To notify the owner when the functions are no longer in use, the
  82                 proto_detached_handler function will be called. It is not safe
  83                 to unload until the proto_detached_handler is called.
  84         @param protocol The protocol family these functions will receive
  85                 packets for.
  86         @param input The function called when a packet is input.
  87         @param inject The function to called when a packet is injected (not
  88                 on the normal input path).
  89         @result A errno error on failure.
  90  */
  91 void    proto_unregister_input(protocol_family_t protocol);
  92 #endif
  93
  94 /*!
  95         @function proto_input
  96         @discussion Inputs a packet on the specified protocol from the input
  97                 path.
  98         @param protocol The protocol of the packet.
  99         @param packet The first packet in a chain of packets to be input.
 100         @result A errno error on failure. Unless proto_input returns zero,
 101                 the caller is responsible for freeing the mbuf.
 102  */
 103 errno_t proto_input(protocol_family_t protocol, mbuf_t packet);
 104
 105 /*!
 106         @function proto_inject
 107         @discussion Injects a packet on the specified protocol from
 108                 anywhere. To avoid recursion, the protocol may need to queue the
 109                 packet to be handled later.
 110         @param protocol The protocol of the packet.
 111         @param packet The first packet in a chain of packets to be injected.
 112         @result A errno error on failure. Unless proto_inject returns zero,
 113                 the caller is responsible for freeing the mbuf.
 114  */
 115 errno_t proto_inject(protocol_family_t protocol, mbuf_t packet);
 116
 117
 118 /****************************************************************************/
 119 /* Protocol plumbing                                                                                                            */
 120 /****************************************************************************/
 121
 122 /*!
 123         @typedef proto_plumb_handler
 124         @discussion proto_plumb_handler is called to attach a protocol to an
 125                 interface. A typical protocol plumb function would fill out an
 126                 ifnet_attach_proto_param and call ifnet_attach_protocol.
 127         @param ifp The interface the protocol should be attached to.
 128         @param protocol_family The protocol that should be attached to the
 129                 interface.
 130         @result
 131                 A non-zero value of the attach failed.
 132  */
 133 typedef errno_t (*proto_plumb_handler)(ifnet_t ifp, protocol_family_t protocol);
 134
 135 /*!
 136         @typedef proto_unplumb_handler
 137         @discussion proto_unplumb_handler is called to detach a protocol
 138                 from an interface. A typical unplumb function would call
 139                 ifnet_detach_protocol and perform any necessary cleanup.
 140         @param ifp The interface the protocol should be detached from.
 141         @param protocol_family The protocol that should be detached from the
 142                 interface.
 143  */
 144 typedef void (*proto_unplumb_handler)(ifnet_t ifp, protocol_family_t protocol);
 145
 146 /*!
 147         @function proto_register_plumber
 148         @discussion Allows the caller to specify the functions called when a protocol
 149                 is attached to an interface belonging to the specified family and when
 150                 that protocol is detached.
 151         @param proto_fam The protocol family these plumbing functions will
 152                 handle.
 153         @param if_fam The interface family these plumbing functions will
 154                 handle.
 155         @param plumb The function to call to attach the protocol to an
 156                 interface.
 157         @param unplumb The function to call to detach the protocol to an
 158                 interface, may be NULL in which case ifnet_detach_protocol will
 159                 be used to detach the protocol.
 160         @result A non-zero value of the attach failed.
 161  */
 162 errno_t proto_register_plumber(protocol_family_t proto_fam, ifnet_family_t if_fam,
 163                                                            proto_plumb_handler plumb, proto_unplumb_handler unplumb);
 164
 165 /*!
 166         @function proto_unregister_plumber
 167         @discussion Unregisters a previously registered plumbing function.
 168         @param proto_fam The protocol family these plumbing functions
 169                 handle.
 170         @param if_fam The interface family these plumbing functions handle.
 171  */
 172 void    proto_unregister_plumber(protocol_family_t proto_fam, ifnet_family_t if_fam);
 173
 174 __END_DECLS
 175
 176 #endif