sys/netgraph/netgraph.h

   1
   2 /*
   3  * netgraph.h
   4  *
   5  * Copyright (c) 1996-1999 Whistle Communications, Inc.
   6  * All rights reserved.
   7  *
   8  * Subject to the following obligations and disclaimer of warranty, use and
   9  * redistribution of this software, in source or object code forms, with or
  10  * without modifications are expressly permitted by Whistle Communications;
  11  * provided, however, that:
  12  * 1. Any and all reproductions of the source or object code must include the
  13  *    copyright notice above and the following disclaimer of warranties; and
  14  * 2. No rights are granted, in any manner or form, to use Whistle
  15  *    Communications, Inc. trademarks, including the mark "WHISTLE
  16  *    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
  17  *    such appears in the above copyright notice or in the software.
  18  *
  19  * THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
  20  * TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
  21  * REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
  22  * INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
  23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
  24  * WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
  25  * REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
  26  * SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
  27  * IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
  28  * RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
  29  * WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
  30  * PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
  31  * SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
  32  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  33  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  34  * THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
  35  * OF SUCH DAMAGE.
  36  *
  37  * Author: Julian Elischer <julian@freebsd.org>
  38  *
  39  * $FreeBSD: src/sys/netgraph/netgraph.h,v 1.6.2.7 2002/04/14 23:31:08 julian Exp $
  40  * $Whistle: netgraph.h,v 1.29 1999/11/01 07:56:13 julian Exp $
  41  */
  42
  43 #ifndef _NETGRAPH_NETGRAPH_H_
  44 #define _NETGRAPH_NETGRAPH_H_
  45
  46 #ifndef _SYS_QUEUE_H_
  47 #include <sys/queue.h>
  48 #endif
  49 #ifndef _SYS_MALLOC_H_
  50 #include <sys/malloc.h>
  51 #endif
  52 #ifndef _SYS_MODULE_H_
  53 #include <sys/module.h>
  54 #endif
  55 #ifndef _SYS_MBUF_H_
  56 #include <sys/mbuf.h>
  57 #endif
  58 #ifndef _NETGRAPH_NG_MESSAGE_H_
  59 #include <netgraph/ng_message.h>
  60 #endif
  61
  62 #ifndef _KERNEL
  63
  64 #error "This file should not be included in user level programs"
  65
  66 #else
  67
  68 #define NG_ABI_VERSION NG_VERSION
  69
  70 /*
  71  * Structure of a hook
  72  */
  73 struct ng_hook {
  74         char   *name;           /* what this node knows this link as */
  75         void   *private;        /* node dependant ID for this hook */
  76         int     flags;          /* info about this hook/link */
  77         int     refs;           /* dont actually free this till 0 */
  78         struct  ng_hook *peer;  /* the other end of this link */
  79         struct  ng_node *node;  /* The node this hook is attached to */
  80         LIST_ENTRY(ng_hook) hooks;      /* linked list of all hooks on node */
  81 };
  82 typedef struct ng_hook *hook_p;
  83
  84 /* Flags for a hook */
  85 #define HK_INVALID              0x0001  /* don't trust it! */
  86
  87 void ng_unref_hook(hook_p hook); /* don't move this */
  88 #define NG_HOOK_REF(hook)       atomic_add_int(&(hook)->refs, 1)
  89 #define NG_HOOK_NAME(hook)      ((hook)->name)
  90 #define NG_HOOK_UNREF(hook)     ng_unref_hook(hook)
  91 #define NG_HOOK_SET_PRIVATE(hook, val)  do {(hook)->private = val;} while (0)
  92 #define NG_HOOK_SET_RCVMSG(hook, val)   do {(hook)->rcvmsg = val;} while (0)
  93 #define NG_HOOK_SET_RCVDATA(hook, val)  do {(hook)->rcvdata = val;} while (0)
  94 #define NG_HOOK_PRIVATE(hook)   ((hook)->private)
  95 #define NG_HOOK_NOT_VALID(hook) ((hook)->flags & HK_INVALID)
  96 #define NG_HOOK_IS_VALID(hook)  (!((hook)->flags & HK_INVALID))
  97 #define NG_HOOK_NODE(hook)      ((hook)->node) /* only rvalue! */
  98 #define NG_HOOK_PEER(hook)      ((hook)->peer) /* only rvalue! */
  99
 100 /* Some shortcuts */
 101 #define NG_PEER_NODE(hook)      NG_HOOK_NODE(NG_HOOK_PEER(hook))
 102 #define NG_PEER_HOOK_NAME(hook) NG_HOOK_NAME(NG_HOOK_PEER(hook))
 103 #define NG_PEER_NODE_NAME(hook) NG_NODE_NAME(NG_PEER_NODE(hook))
 104
 105 /*
 106  * Structure of a node
 107  */
 108 struct ng_node {
 109         char   *name;           /* optional globally unique name */
 110         struct  ng_type *type;  /* the installed 'type' */
 111         int     flags;          /* see below for bit definitions */
 112         int     sleepers;       /* #procs sleeping on this node */
 113         int     refs;           /* number of references to this node */
 114         int     numhooks;       /* number of hooks */
 115         int     colour;         /* for graph colouring algorithms */
 116         void   *private;        /* node type dependant node ID */
 117         ng_ID_t         ID;     /* Unique per node */
 118         LIST_HEAD(hooks, ng_hook) hooks;        /* linked list of node hooks */
 119         LIST_ENTRY(ng_node)       nodes;        /* linked list of all nodes */
 120         LIST_ENTRY(ng_node)       idnodes;      /* ID hash collision list */
 121 };
 122 typedef struct ng_node *node_p;
 123
 124 /* Flags for a node */
 125 #define NG_INVALID      0x001   /* free when all sleepers and refs go to 0 */
 126 #define NG_BUSY         0x002   /* callers should sleep or wait */
 127 #define NG_TOUCHED      0x004   /* to avoid cycles when 'flooding' */
 128 #define NGF_TYPE1       0x10000000      /* reserved for type specific storage */
 129 #define NGF_TYPE2       0x20000000      /* reserved for type specific storage */
 130 #define NGF_TYPE3       0x40000000      /* reserved for type specific storage */
 131 #define NGF_TYPE4       0x80000000      /* reserved for type specific storage */
 132
 133 void    ng_unref_node(node_p node); /* don't move this */
 134 #define NG_NODE_NAME(node)      ((node)->name + 0)
 135 #define NG_NODE_HAS_NAME(node)  ((node)->name[0] + 0)
 136 #define NG_NODE_ID(node)        ((node)->ID + 0)
 137 #define NG_NODE_REF(node)       atomic_add_int(&(node)->refs, 1)
 138 #define NG_NODE_UNREF(node)     ng_unref(node)
 139 #define NG_NODE_SET_PRIVATE(node, val)  do {(node)->private = val;} while (0)
 140 #define NG_NODE_PRIVATE(node)   ((node)->private)
 141 #define NG_NODE_IS_VALID(node)  (!((node)->flags & NG_INVALID))
 142 #define NG_NODE_NOT_VALID(node) ((node)->flags & NG_INVALID)
 143 #define NG_NODE_NUMHOOKS(node)  ((node)->numhooks + 0) /* rvalue */
 144
 145 /*
 146  * The structure that holds meta_data about a data packet (e.g. priority)
 147  * Nodes might add or subtract options as needed if there is room.
 148  * They might reallocate the struct to make more room if they need to.
 149  * Meta-data is still experimental.
 150  */
 151 struct meta_field_header {
 152         u_long  cookie;         /* cookie for the field. Skip fields you don't
 153                                  * know about (same cookie as in messgaes) */
 154         u_short type;           /* field ID */
 155         u_short len;            /* total len of this field including extra
 156                                  * data */
 157         char    data[0];        /* data starts here */
 158 };
 159
 160 /* To zero out an option 'in place' set it's cookie to this */
 161 #define NGM_INVALID_COOKIE      865455152
 162
 163 /* This part of the metadata is always present if the pointer is non NULL */
 164 struct ng_meta {
 165         char    priority;       /* -ve is less priority,  0 is default */
 166         char    discardability; /* higher is less valuable.. discard first */
 167         u_short allocated_len;  /* amount malloc'd */
 168         u_short used_len;       /* sum of all fields, options etc. */
 169         u_short flags;          /* see below.. generic flags */
 170         struct meta_field_header options[0];    /* add as (if) needed */
 171 };
 172 typedef struct ng_meta *meta_p;
 173
 174 /* Flags for meta-data */
 175 #define NGMF_TEST       0x01    /* discard at the last moment before sending */
 176 #define NGMF_TRACE      0x02    /* trace when handing this data to a node */
 177
 178 /* node method definitions */
 179 typedef int     ng_constructor_t(node_p *node);
 180 typedef int     ng_rcvmsg_t(node_p node, struct ng_mesg *msg,
 181                         const char *retaddr, struct ng_mesg **resp);
 182 typedef int     ng_shutdown_t(node_p node);
 183 typedef int     ng_newhook_t(node_p node, hook_p hook, const char *name);
 184 typedef hook_p  ng_findhook_t(node_p node, const char *name);
 185 typedef int     ng_connect_t(hook_p hook);
 186 typedef int     ng_rcvdata_t(hook_p hook, struct mbuf *m, meta_p meta);
 187 typedef int     ng_disconnect_t(hook_p hook);
 188
 189 /*
 190  * Command list -- each node type specifies the command that it knows
 191  * how to convert between ASCII and binary using an array of these.
 192  * The last element in the array must be a terminator with cookie=0.
 193  */
 194
 195 struct ng_cmdlist {
 196         u_int32_t                       cookie;         /* command typecookie */
 197         int                             cmd;            /* command number */
 198         const char                      *name;          /* command name */
 199         const struct ng_parse_type      *mesgType;      /* args if !NGF_RESP */
 200         const struct ng_parse_type      *respType;      /* args if NGF_RESP */
 201 };
 202
 203 /*
 204  * Structure of a node type
 205  */
 206 struct ng_type {
 207
 208         u_int32_t       version;        /* must equal NG_VERSION */
 209         const char      *name;          /* Unique type name */
 210         modeventhand_t  mod_event;      /* Module event handler (optional) */
 211         ng_constructor_t *constructor;  /* Node constructor */
 212         ng_rcvmsg_t     *rcvmsg;        /* control messages come here */
 213         ng_shutdown_t   *shutdown;      /* reset, and free resources */
 214         ng_newhook_t    *newhook;       /* first notification of new hook */
 215         ng_findhook_t   *findhook;      /* only if you have lots of hooks */
 216         ng_connect_t    *connect;       /* final notification of new hook */
 217         ng_rcvdata_t    *rcvdata;       /* date comes here */
 218         ng_rcvdata_t    *rcvdataq;      /* or here if being queued */
 219         ng_disconnect_t *disconnect;    /* notify on disconnect */
 220
 221         const struct    ng_cmdlist *cmdlist;    /* commands we can convert */
 222
 223         /* R/W data private to the base netgraph code DON'T TOUCH! */
 224         LIST_ENTRY(ng_type) types;              /* linked list of all types */
 225         int                 refs;               /* number of instances */
 226 };
 227
 228 /* Send data packet with meta-data */
 229 #define NG_SEND_DATA(error, hook, m, a)                                 \
 230         do {                                                            \
 231                 (error) = ng_send_data((hook), (m), (a));               \
 232                 (m) = NULL;                                             \
 233                 (a) = NULL;                                             \
 234         } while (0)
 235
 236 #define NG_SEND_DATA_ONLY(error, hook, m)                               \
 237         do {                                                            \
 238                 (error) = ng_send_data((hook), (m), NULL);              \
 239                 (m) = NULL;                                             \
 240         } while (0)
 241
 242 /* Send  queued data packet with meta-data */
 243 #define NG_SEND_DATAQ(error, hook, m, a)                                \
 244         do {                                                            \
 245                 (error) = ng_send_dataq((hook), (m), (a));              \
 246                 (m) = NULL;                                             \
 247                 (a) = NULL;                                             \
 248         } while (0)
 249
 250 #define NG_RESPOND_MSG(error, here, retaddr, resp, rptr)                \
 251         do {                                                            \
 252                 if (rptr) {                                             \
 253                         *rptr = resp;                                   \
 254                 } else if (resp) {                                      \
 255                         if (retaddr) {                                  \
 256                                 error = ng_queue_msg(here, resp, retaddr); \
 257                         } else {                                        \
 258                                 FREE(resp, M_NETGRAPH);                 \
 259                         }                                               \
 260                 }                                                       \
 261         } while (0)
 262
 263 #define NG_FREE_MSG(msg)                                                \
 264         do {                                                            \
 265                 if ((msg)) {                                            \
 266                         FREE((msg), M_NETGRAPH);                        \
 267                         (msg) = NULL;                                   \
 268                 }                                                       \
 269         } while (0)
 270
 271 #define NG_FREE_META(a)                                                 \
 272         do {                                                            \
 273                 if ((a)) {                                              \
 274                         FREE((a), M_NETGRAPH);                          \
 275                         (a) = NULL;                                     \
 276                 }                                                       \
 277         } while (0)
 278
 279 #define NG_FREE_M(m)                                                    \
 280         do {                                                            \
 281                 if ((m)) {                                              \
 282                         m_freem((m));                                   \
 283                         (m) = NULL;                                     \
 284                 }                                                       \
 285         } while (0)
 286
 287 /* Free any data packet and/or meta-data */
 288 #define NG_FREE_DATA(m, a)                                              \
 289         do {                                                            \
 290                 NG_FREE_M((m));                                         \
 291                 NG_FREE_META((a));                                      \
 292         } while (0)
 293
 294 /*
 295  * Use the NETGRAPH_INIT() macro to link a node type into the
 296  * netgraph system. This works for types compiled into the kernel
 297  * as well as KLD modules. The first argument should be the type
 298  * name (eg, echo) and the second a pointer to the type struct.
 299  *
 300  * If a different link time is desired, e.g., a device driver that
 301  * needs to install its netgraph type before probing, use the
 302  * NETGRAPH_INIT_ORDERED() macro instead. Deivce drivers probably
 303  * want to use SI_SUB_DRIVERS instead of SI_SUB_PSEUDO.
 304  */
 305
 306 #define NETGRAPH_INIT_ORDERED(typename, typestructp, sub, order)        \
 307 static moduledata_t ng_##typename##_mod = {                             \
 308         "ng_" #typename,                                                \
 309         ng_mod_event,                                                   \
 310         (typestructp)                                                   \
 311 };                                                                      \
 312 DECLARE_MODULE(ng_##typename, ng_##typename##_mod, sub, order);         \
 313 MODULE_VERSION(ng_##typename, NG_ABI_VERSION);                          \
 314 MODULE_DEPEND(ng_##typename, netgraph,  NG_ABI_VERSION,                 \
 315                                         NG_ABI_VERSION,                 \
 316                                         NG_ABI_VERSION)
 317 #define NETGRAPH_INIT(tn, tp)                                           \
 318         NETGRAPH_INIT_ORDERED(tn, tp, SI_SUB_PSEUDO, SI_ORDER_ANY)
 319
 320 /* Special malloc() type for netgraph structs and ctrl messages */
 321 MALLOC_DECLARE(M_NETGRAPH);
 322
 323 /* declare the base of the netgraph sysctl hierarchy */
 324 /* but only if this file cares about sysctls */
 325 #ifdef  SYSCTL_DECL
 326 SYSCTL_DECL(_net_graph);
 327 #endif
 328
 329 int     ng_bypass(hook_p hook1, hook_p hook2);
 330 void    ng_cutlinks(node_p node);
 331 int     ng_con_nodes(node_p node,
 332              const char *name, node_p node2, const char *name2);
 333 meta_p  ng_copy_meta(meta_p meta);
 334 void    ng_destroy_hook(hook_p hook);
 335 hook_p  ng_findhook(node_p node, const char *name);
 336 node_p  ng_findname(node_p node, const char *name);
 337 struct  ng_type *ng_findtype(const char *type);
 338 int     ng_make_node(const char *type, node_p *nodepp);
 339 int     ng_make_node_common(struct ng_type *typep, node_p *nodep);
 340 int     ng_mkpeer(node_p node, const char *name, const char *name2, char *type);
 341 int     ng_mod_event(module_t mod, int what, void *arg);
 342 int     ng_name_node(node_p node, const char *name);
 343 int     ng_newtype(struct ng_type *tp);
 344 ng_ID_t ng_node2ID(node_p node);
 345 int     ng_path2node(node_p here, const char *path, node_p *dest, char **rtnp);
 346 int     ng_path_parse(char *addr, char **node, char **path, char **hook);
 347 int     ng_queue_data(hook_p hook, struct mbuf *m, meta_p meta);
 348 int     ng_queue_msg(node_p here, struct ng_mesg *msg, const char *address);
 349 void    ng_release_node(node_p node);
 350 void    ng_rmnode(node_p node);
 351 int     ng_send_data(hook_p hook, struct mbuf *m, meta_p meta);
 352 int     ng_send_dataq(hook_p hook, struct mbuf *m, meta_p meta);
 353 int     ng_send_msg(node_p here, struct ng_mesg *msg,
 354             const char *address, struct ng_mesg **resp);
 355 void    ng_unname(node_p node);
 356 void    ng_unref(node_p node);
 357 int     ng_wait_node(node_p node, char *msg);
 358
 359 #endif  /* _KERNEL */
 360 #endif  /* _NETGRAPH_NETGRAPH_H_ */
 361