Part 2 of the netgraph rewrite.

This is mostly cosmetic changes, (though I caught a bug or two while
makeing them)
Reviewed by:	archie@freebsd.org

1 files changed, 564 insertions, 171 deletions

diff --git a/sys/netgraph/netgraph.h b/sys/netgraph/netgraph.h
index 323aacc..b3c6afc 100644
--- a/sys/netgraph/netgraph.h
+++ b/sys/netgraph/netgraph.h
@@ -1,4 +1,3 @@
-
 /*
  * netgraph.h
  *
@@ -43,64 +42,266 @@
 #ifndef _NETGRAPH_NETGRAPH_H_
 #define _NETGRAPH_NETGRAPH_H_ 1
 
-#include <sys/queue.h>
-#include <sys/malloc.h>
-#include <sys/module.h>
-
 #ifndef _KERNEL
 #error "This file should not be included in user level programs"
 #endif
 
+#include <sys/queue.h>
+#include <sys/malloc.h>
+#include <sys/module.h>
 #include <sys/mutex.h>
 
-/* The structure for queueing across ISR switches */
-struct ng_item ; /* forward reference */
-typedef	struct ng_item *item_p;
-struct ng_queue {
-	u_long          q_flags;
-	struct mtx      q_mtx;
-	item_p queue;
-	item_p *last;
-	struct ng_node *q_node;		/* find the front of the node.. */
-};
+#define NETGRAPH_DEBUG 
 
 /*
+ * This defines the in-kernel binary interface version.
+ * It is possible to change this but leave the external message
+ * API the same. Each type also has it's own cookies for versioning as well.
+ * Change it for NETGRAPH_DEBUG version so we cannot mix debug and non debug
+ * modules.
+ */
+#define _NG_ABI_VERSION 5
+#ifdef	NETGRAPH_DEBUG /*----------------------------------------------*/
+#define NG_ABI_VERSION	(_NG_ABI_VERSION + 0x10000)
+#else	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
+#define NG_ABI_VERSION	_NG_ABI_VERSION
+#endif	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
+
+
+/*
+ * Forward references for the basic structures so we can
+ * define the typedefs and use them in the structures themselves.
+ */
+struct ng_hook ;
+struct ng_node ;
+struct ng_item ;
+typedef	struct ng_item *item_p;
+typedef struct ng_node *node_p;
+typedef struct ng_hook *hook_p;
+
+/***********************************************************************
+ ***************** Hook Structure and Methods **************************
+ ***********************************************************************
+ *
  * Structure of a hook
  */
 struct ng_hook {
-	char   name[NG_HOOKLEN+1];/* what this node knows this link as */
-	void   *private;	/* node dependant ID for this hook */
-	int	flags;		/* info about this hook/link */
-	int	refs;		/* dont actually free this till 0 */
-	struct	ng_hook *peer;	/* the other end of this link */
-	struct	ng_node *node;	/* The node this hook is attached to */
-	LIST_ENTRY(ng_hook) hooks;	/* linked list of all hooks on node */
+	char	hk_name[NG_HOOKLEN+1];	/* what this node knows this link as */
+	void   *hk_private;		/* node dependant ID for this hook */
+	int	hk_flags;		/* info about this hook/link */
+	int	hk_refs;		/* dont actually free this till 0 */
+	struct	ng_hook *hk_peer;	/* the other end of this link */
+	struct	ng_node *hk_node;	/* The node this hook is attached to */
+	LIST_ENTRY(ng_hook) hk_hooks;	/* linked list of all hooks on node */
+#ifdef	NETGRAPH_DEBUG /*----------------------------------------------*/
+#define HK_MAGIC 0x78573011
+	int	hk_magic;
+	char	*lastfile;
+	int	lastline;
+	SLIST_ENTRY(ng_hook)	  hk_all;		/* all existing items */
+#endif	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
 };
-typedef struct ng_hook *hook_p;
-
 /* Flags for a hook */
 #define HK_INVALID		0x0001	/* don't trust it! */
 #define HK_QUEUE		0x0002	/* queue for later delivery */
 #define HK_FORCE_WRITER		0x0004	/* Incoming data queued as a writer */
 
 /*
+ * Public Methods for hook
+ * If you can't do it with these you probably shouldn;t be doing it.
+ */
+void ng_unref_hook(hook_p hook); /* don't move this */
+#define	_NG_HOOK_REF(hook)	atomic_add_int(&(hook)->hk_refs, 1)
+#define _NG_HOOK_NAME(hook)	((hook)->hk_name)
+#define _NG_HOOK_UNREF(hook)	ng_unref_hook(hook)
+#define	_NG_HOOK_SET_PRIVATE(hook, val)	do {(hook)->hk_private = val;} while (0)
+#define	_NG_HOOK_PRIVATE(hook)	((hook)->hk_private)
+#define _NG_HOOK_NOT_VALID(hook)	((hook)->hk_flags & HK_INVALID)
+#define _NG_HOOK_IS_VALID(hook)	(!(hook)->hk_flags & HK_INVALID)
+#define _NG_HOOK_NODE(hook)	((hook)->hk_node) /* only rvalue! */
+#define _NG_HOOK_PEER(hook)	((hook)->hk_peer) /* only rvalue! */
+#define _NG_HOOK_FORCE_WRITER(hook)				\
+		do { hook->hk_flags |= HK_FORCE_WRITER; } while (0)
+#define _NG_HOOK_FORCE_QUEUE(hook) do { hook->hk_flags |= HK_QUEUE; } while (0)
+
+/* Some shortcuts */
+#define NG_PEER_NODE(hook)	NG_HOOK_NODE(NG_HOOK_PEER(hook))
+#define NG_PEER_HOOK_NAME(hook)	NG_HOOK_NAME(NG_HOOK_PEER(hook))
+#define NG_PEER_NODE_NAME(hook)	NG_NODE_NAME(NG_PEER_NODE(hook))
+
+#ifdef	NETGRAPH_DEBUG /*----------------------------------------------*/
+#define _NN_ __FILE__,__LINE__
+void	dumphook (hook_p hook, char *file, int line);
+static __inline void	_chkhook(hook_p hook, char *file, int line);
+static __inline void	_ng_hook_ref(hook_p hook, char * file, int line);
+static __inline char *	_ng_hook_name(hook_p hook, char * file, int line);
+static __inline void	_ng_hook_unref(hook_p hook, char * file, int line);
+static __inline void	_ng_hook_set_private(hook_p hook,
+					void * val, char * file, int line);
+static __inline void *	_ng_hook_private(hook_p hook, char * file, int line);
+static __inline int	_ng_hook_not_valid(hook_p hook, char * file, int line);
+static __inline int	_ng_hook_is_valid(hook_p hook, char * file, int line);
+static __inline node_p	_ng_hook_node(hook_p hook, char * file, int line);
+static __inline hook_p	_ng_hook_peer(hook_p hook, char * file, int line);
+static __inline void	_ng_hook_force_writer(hook_p hook, char * file,
+					int line);
+static __inline void	_ng_hook_force_queue(hook_p hook, char * file, int line);
+
+static void __inline 
+_chkhook(hook_p hook, char *file, int line)
+{
+	if (hook->hk_magic != HK_MAGIC) {
+		printf("Accessing freed hook ");
+		dumphook(hook, file, line);
+	}
+	hook->lastline = line;
+	hook->lastfile = file;
+}
+
+static __inline void
+_ng_hook_ref(hook_p hook, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	_NG_HOOK_REF(hook);
+} 
+
+static __inline char *
+_ng_hook_name(hook_p hook, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	return (_NG_HOOK_NAME(hook));
+} 
+
+static __inline void
+_ng_hook_unref(hook_p hook, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	_NG_HOOK_UNREF(hook);
+} 
+
+static __inline void
+_ng_hook_set_private(hook_p hook, void *val, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	_NG_HOOK_SET_PRIVATE(hook, val);
+} 
+
+static __inline void *
+_ng_hook_private(hook_p hook, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	return (_NG_HOOK_PRIVATE(hook));
+} 
+
+static __inline int
+_ng_hook_not_valid(hook_p hook, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	return (_NG_HOOK_NOT_VALID(hook));
+} 
+
+static __inline int
+_ng_hook_is_valid(hook_p hook, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	return (_NG_HOOK_IS_VALID(hook));
+} 
+
+static __inline node_p
+_ng_hook_node(hook_p hook, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	return (_NG_HOOK_NODE(hook));
+} 
+
+static __inline hook_p
+_ng_hook_peer(hook_p hook, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	return (_NG_HOOK_PEER(hook));
+} 
+
+static __inline void
+_ng_hook_force_writer(hook_p hook, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	_NG_HOOK_FORCE_WRITER(hook);
+} 
+
+static __inline void
+_ng_hook_force_queue(hook_p hook, char * file, int line)
+{
+	_chkhook(hook, file, line);
+	_NG_HOOK_FORCE_QUEUE(hook);
+} 
+
+
+#define	NG_HOOK_REF(hook)		_ng_hook_ref(hook, _NN_)
+#define NG_HOOK_NAME(hook)		_ng_hook_name(hook, _NN_)
+#define NG_HOOK_UNREF(hook)		_ng_hook_unref(hook, _NN_)
+#define	NG_HOOK_SET_PRIVATE(hook, val)	_ng_hook_set_private(hook, val, _NN_)
+#define	NG_HOOK_PRIVATE(hook)		_ng_hook_private(hook, _NN_)
+#define NG_HOOK_NOT_VALID(hook)		_ng_hook_not_valid(hook, _NN_)
+#define NG_HOOK_IS_VALID(hook)		_ng_hook_is_valid(hook, _NN_)
+#define NG_HOOK_NODE(hook)		_ng_hook_node(hook, _NN_)
+#define NG_HOOK_PEER(hook)		_ng_hook_peer(hook, _NN_)
+#define NG_HOOK_FORCE_WRITER(hook)	_ng_hook_force_writer(hook, _NN_)
+#define NG_HOOK_FORCE_QUEUE(hook)	_ng_hook_force_queue(hook, _NN_)
+
+#else	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
+
+#define	NG_HOOK_REF(hook)		_NG_HOOK_REF(hook)
+#define NG_HOOK_NAME(hook)		_NG_HOOK_NAME(hook)
+#define NG_HOOK_UNREF(hook)		_NG_HOOK_UNREF(hook)
+#define	NG_HOOK_SET_PRIVATE(hook, val)	_NG_HOOK_SET_PRIVATE(hook, val)
+#define	NG_HOOK_PRIVATE(hook)		_NG_HOOK_PRIVATE(hook)
+#define NG_HOOK_NOT_VALID(hook)		_NG_HOOK_NOT_VALID(hook)
+#define NG_HOOK_IS_VALID(hook)		_NG_HOOK_IS_VALID(hook)
+#define NG_HOOK_NODE(hook)		_NG_HOOK_NODE(hook)
+#define NG_HOOK_PEER(hook)		_NG_HOOK_PEER(hook)
+#define NG_HOOK_FORCE_WRITER(hook)	_NG_HOOK_FORCE_WRITER(hook)
+#define NG_HOOK_FORCE_QUEUE(hook)	_NG_HOOK_FORCE_QUEUE(hook)
+
+#endif	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
+
+/***********************************************************************
+ ***************** Node Structure and Methods **************************
+ ***********************************************************************
  * Structure of a node
+ * including the eembedded queue structure.
+ *
+ * The structure for queueing Netgraph request items 
+ * embedded in the node structure
  */
+struct ng_queue {
+	u_long          q_flags;
+	struct mtx      q_mtx;
+	item_p queue;
+	item_p *last;
+	struct ng_node *q_node;		/* find the front of the node.. */
+};
+
 struct ng_node {
-	char   name[NG_NODELEN+1]; /* optional globally unique name */
-	struct	ng_type *type;	/* the installed 'type' */
-	int	flags;		/* see below for bit definitions */
-	int	refs;		/* number of references to this node */
-	int	numhooks;	/* number of hooks */
-	void   *private;	/* node type dependant node ID */
-	ng_ID_t		ID;	/* Unique per node */
-	LIST_HEAD(hooks, ng_hook) hooks;	/* linked list of node hooks */
-	LIST_ENTRY(ng_node)	  nodes;	/* linked list of all nodes */
-	LIST_ENTRY(ng_node)	  idnodes;	/* ID hash collision list */
-	TAILQ_ENTRY(ng_node)	  work;		/* nodes with work to do */
-	struct	ng_queue	  input_queue;	/* input queue for locking */
+	char	nd_name[NG_NODELEN+1];	/* optional globally unique name */
+	struct	ng_type *nd_type;	/* the installed 'type' */
+	int	nd_flags;		/* see below for bit definitions */
+	int	nd_refs;		/* # of references to this node */
+	int	nd_numhooks;		/* number of hooks */
+	void   *nd_private;		/* node type dependant node ID */
+	ng_ID_t	nd_ID;			/* Unique per node */
+	LIST_HEAD(hooks, ng_hook) nd_hooks;	/* linked list of node hooks */
+	LIST_ENTRY(ng_node)	  nd_nodes;	/* linked list of all nodes */
+	LIST_ENTRY(ng_node)	  nd_idnodes;	/* ID hash collision list */
+	TAILQ_ENTRY(ng_node)	  nd_work;	/* nodes with work to do */
+	struct	ng_queue	  nd_input_queue; /* input queue for locking */
+#ifdef	NETGRAPH_DEBUG /*----------------------------------------------*/
+#define ND_MAGIC 0x59264837
+	int	nd_magic;
+	char	*lastfile;
+	int	lastline;
+	SLIST_ENTRY(ng_node)	  nd_all;	/* all existing nodes */
+#endif	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
 };
-typedef struct ng_node *node_p;
 
 /* Flags for a node */
 #define NG_INVALID	0x00000001	/* free when refs go to 0 */
@@ -113,6 +314,193 @@ typedef struct ng_node *node_p;
 #define NGF_TYPE4	0x80000000	/* reserved for type specific storage */
 
 /*
+ * Public methods for nodes.
+ * If you can't do it with these you probably shouldn't be doing it.
+ */
+void	ng_unref_node(node_p node); /* don't move this */
+#define _NG_NODE_NAME(node)	((node)->nd_name + 0)
+#define _NG_NODE_HAS_NAME(node)	((node)->nd_name[0] + 0)
+#define _NG_NODE_ID(node)	((node)->nd_ID + 0)
+#define	_NG_NODE_REF(node)	atomic_add_int(&(node)->nd_refs, 1)
+#define	_NG_NODE_UNREF(node)	ng_unref_node(node)
+#define	_NG_NODE_SET_PRIVATE(node, val)	do {(node)->nd_private = val;} while (0)
+#define	_NG_NODE_PRIVATE(node)	((node)->nd_private)
+#define _NG_NODE_IS_VALID(node)	(!((node)->nd_flags & NG_INVALID))
+#define _NG_NODE_NOT_VALID(node)	((node)->nd_flags & NG_INVALID)
+#define _NG_NODE_NUMHOOKS(node)	((node)->nd_numhooks + 0) /* rvalue */
+#define _NG_NODE_FORCE_WRITER(node)					\
+	do{ node->nd_flags |= NG_FORCE_WRITER; }while (0)
+/*
+ * The hook iterator.
+ * This macro will call a function of type ng_fn_eachhook for each
+ * hook attached to the node. If the function returns 0, then the
+ * iterator will stop and return a pointer to the hook that returned 0.
+ */
+typedef	int	ng_fn_eachhook(hook_p hook, void* arg);
+#define _NG_NODE_FOREACH_HOOK(node, fn, arg, rethook)			\
+	do {								\
+		hook_p hook;						\
+		LIST_FOREACH(hook, &((node)->nd_hooks), hk_hooks) {	\
+			if ((fn)(hook, arg) == 0) {			\
+				(rethook) = hook;			\
+				break;					\
+			}						\
+		}							\
+	} while (0)
+
+#ifdef	NETGRAPH_DEBUG /*----------------------------------------------*/
+void	dumpnode(node_p node, char *file, int line);
+static void __inline _chknode(node_p node, char *file, int line);
+static __inline char * _ng_node_name(node_p node, char *file, int line);
+static __inline int _ng_node_has_name(node_p node, char *file, int line);
+static __inline ng_ID_t _ng_node_id(node_p node, char *file, int line);
+static __inline void _ng_node_ref(node_p node, char *file, int line);
+static __inline void _ng_node_unref(node_p node, char *file, int line);
+static __inline void _ng_node_set_private(node_p node, void * val,
+							char *file, int line);
+static __inline void * _ng_node_private(node_p node, char *file, int line);
+static __inline int _ng_node_is_valid(node_p node, char *file, int line);
+static __inline int _ng_node_not_valid(node_p node, char *file, int line);
+static __inline int _ng_node_numhooks(node_p node, char *file, int line);
+static __inline void _ng_node_force_writer(node_p node, char *file, int line);
+static __inline hook_p _ng_node_foreach_hook(node_p node,
+			ng_fn_eachhook *fn, void *arg, char *file, int line);
+
+static void __inline 
+_chknode(node_p node, char *file, int line)
+{
+	if (node->nd_magic != ND_MAGIC) {
+		printf("Accessing freed node ");
+		dumpnode(node, file, line);
+	}
+	node->lastline = line;
+	node->lastfile = file;
+}
+
+static __inline char *
+_ng_node_name(node_p node, char *file, int line)
+{
+	_chknode(node, file, line);
+	return(_NG_NODE_NAME(node));
+}
+
+static __inline int 
+_ng_node_has_name(node_p node, char *file, int line)
+{
+	_chknode(node, file, line);
+	return(_NG_NODE_HAS_NAME(node));
+}
+
+static __inline ng_ID_t
+_ng_node_id(node_p node, char *file, int line)
+{
+	_chknode(node, file, line);
+	return(_NG_NODE_ID(node));
+}
+
+static __inline void 
+_ng_node_ref(node_p node, char *file, int line)
+{
+	_chknode(node, file, line);
+	_NG_NODE_REF(node);
+}
+
+static __inline void
+_ng_node_unref(node_p node, char *file, int line)
+{
+	_chknode(node, file, line);
+	_NG_NODE_UNREF(node);
+}
+
+static __inline void
+_ng_node_set_private(node_p node, void * val, char *file, int line)
+{
+	_chknode(node, file, line);
+	_NG_NODE_SET_PRIVATE(node, val);
+}
+
+static __inline void *
+_ng_node_private(node_p node, char *file, int line)
+{
+	_chknode(node, file, line);
+	return (_NG_NODE_PRIVATE(node));
+}
+
+static __inline int
+_ng_node_is_valid(node_p node, char *file, int line)
+{
+	_chknode(node, file, line);
+	return(_NG_NODE_IS_VALID(node));
+}
+
+static __inline int
+_ng_node_not_valid(node_p node, char *file, int line)
+{
+	_chknode(node, file, line);
+	return(_NG_NODE_NOT_VALID(node));
+}
+
+static __inline int
+_ng_node_numhooks(node_p node, char *file, int line)
+{
+	_chknode(node, file, line);
+	return(_NG_NODE_NUMHOOKS(node));
+}
+
+static __inline void
+_ng_node_force_writer(node_p node, char *file, int line)
+{
+	_chknode(node, file, line);
+	_NG_NODE_FORCE_WRITER(node);
+}
+
+static __inline hook_p
+_ng_node_foreach_hook(node_p node, ng_fn_eachhook *fn, void *arg,
+						char *file, int line)
+{
+	hook_p hook;
+	_chknode(node, file, line);
+	_NG_NODE_FOREACH_HOOK(node, fn, arg, hook);
+	return (hook);
+}
+
+#define NG_NODE_NAME(node)		_ng_node_name(node, _NN_)	
+#define NG_NODE_HAS_NAME(node)		_ng_node_has_name(node, _NN_)	
+#define NG_NODE_ID(node)		_ng_node_ID(node, _NN_)
+#define NG_NODE_REF(node)		_ng_node_ref(node, _NN_)
+#define	NG_NODE_UNREF(node)		_ng_node_unref(node, _NN_)
+#define	NG_NODE_SET_PRIVATE(node, val)	_ng_node_set_private(node, val, _NN_)
+#define	NG_NODE_PRIVATE(node)		_ng_node_private(node, _NN_)
+#define NG_NODE_IS_VALID(node)		_ng_node_is_valid(node, _NN_)
+#define NG_NODE_NOT_VALID(node)		_ng_node_not_valid(node, _NN_)
+#define NG_NODE_FORCE_WRITER(node) 	_ng_node_force_writer(node, _NN_)
+#define NG_NODE_NUMHOOKS(node)		_ng_node_numhooks(node, _NN_)
+#define NG_NODE_FOREACH_HOOK(node, fn, arg, rethook)			      \
+	do {								      \
+		rethook = _ng_node_foreach_hook(node, fn, (void *)arg, _NN_); \
+	} while (0)
+
+#else	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
+
+#define NG_NODE_NAME(node)		_NG_NODE_NAME(node)	
+#define NG_NODE_HAS_NAME(node)		_NG_NODE_HAS_NAME(node)	
+#define NG_NODE_ID(node)		_NG_NODE_ID(node)	
+#define	NG_NODE_REF(node)		_NG_NODE_REF(node)	
+#define	NG_NODE_UNREF(node)		_NG_NODE_UNREF(node)	
+#define	NG_NODE_SET_PRIVATE(node, val)	_NG_NODE_SET_PRIVATE(node, val)	
+#define	NG_NODE_PRIVATE(node)		_NG_NODE_PRIVATE(node)	
+#define NG_NODE_IS_VALID(node)		_NG_NODE_IS_VALID(node)	
+#define NG_NODE_NOT_VALID(node)		_NG_NODE_NOT_VALID(node)	
+#define NG_NODE_FORCE_WRITER(node) 	_NG_NODE_FORCE_WRITER(node)
+#define NG_NODE_NUMHOOKS(node)		_NG_NODE_NUMHOOKS(node)	
+#define NG_NODE_FOREACH_HOOK(node, fn, arg, rethook)			\
+		_NG_NODE_FOREACH_HOOK(node, fn, arg, rethook)
+#endif	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
+
+/***********************************************************************
+ ***************** Meta Data Structures and Methods ********************
+ ***********************************************************************
+ *
  * The structure that holds meta_data about a data packet (e.g. priority)
  * Nodes might add or subtract options as needed if there is room.
  * They might reallocate the struct to make more room if they need to.
@@ -145,64 +533,11 @@ typedef struct ng_meta *meta_p;
 #define NGMF_TEST	0x01	/* discard at the last moment before sending */
 #define NGMF_TRACE	0x02	/* trace when handing this data to a node */
 
-/* node method definitions */
-typedef	int	ng_constructor_t(node_p node);
-typedef	int	ng_rcvmsg_t(node_p node, item_p item, hook_p lasthook);
-typedef	int	ng_shutdown_t(node_p node);
-typedef	int	ng_newhook_t(node_p node, hook_p hook, const char *name);
-typedef	hook_p	ng_findhook_t(node_p node, const char *name);
-typedef	int	ng_connect_t(hook_p hook);
-typedef	int	ng_rcvdata_t(hook_p hook, item_p item);
-typedef	int	ng_disconnect_t(hook_p hook);
-typedef	int	ng_rcvitem (node_p node, hook_p hook, item_p item);
-/*
- * Command list -- each node type specifies the command that it knows
- * how to convert between ASCII and binary using an array of these.
- * The last element in the array must be a terminator with cookie=0.
- */
-
-struct ng_cmdlist {
-	u_int32_t			cookie;		/* command typecookie */
-	int				cmd;		/* command number */
-	const char			*name;		/* command name */
-	const struct ng_parse_type	*mesgType;	/* args if !NGF_RESP */
-	const struct ng_parse_type	*respType;	/* args if NGF_RESP */
-};
-
-/*
- * Structure of a node type
- * If data is sent to the "rcvdata()" entrypoint then the system
- * may decide to defer it until later by queing it with the normal netgraph
- * input queuing system.  This is decidde by the HK_QUEUE flag being set in
- * the flags word of the peer (receiving) hook. The dequeuing mechanism will
- * ensure it is not requeued again.
- * Note the input queueing system is to allow modules
- * to 'release the stack' or to pass data across spl layers.
- * The data will be redelivered as soon as the NETISR code runs
- * which may be almost immediatly.  A node may also do it's own queueing
- * for other reasons (e.g. device output queuing).
+/***********************************************************************
+ ************* Node Queue and Item Structures and Methods **************
+ ***********************************************************************
+ *
  */
-struct ng_type {
-
-	u_int32_t	version; 	/* must equal NG_API_VERSION */
-	const char	*name;		/* Unique type name */
-	modeventhand_t	mod_event;	/* Module event handler (optional) */
-	ng_constructor_t *constructor;	/* Node constructor */
-	ng_rcvmsg_t	*rcvmsg;	/* control messages come here */
-	ng_shutdown_t	*shutdown;	/* reset, and free resources */
-	ng_newhook_t	*newhook;	/* first notification of new hook */
-	ng_findhook_t	*findhook;	/* only if you have lots of hooks */
-	ng_connect_t	*connect;	/* final notification of new hook */
-	ng_rcvdata_t	*rcvdata;	/* data comes here */
-	ng_disconnect_t	*disconnect;	/* notify on disconnect */
-
-	const struct	ng_cmdlist *cmdlist;	/* commands we can convert */
-
-	/* R/W data private to the base netgraph code DON'T TOUCH! */
-	LIST_ENTRY(ng_type) types;		/* linked list of all types */
-	int		    refs;		/* number of instances */
-};
-
 struct ng_item {
 	u_long	el_flags;
 	item_p	el_next;
@@ -218,12 +553,11 @@ struct ng_item {
 			ng_ID_t		msg_retaddr;
 		} msg;
 	} body;
-#define ITEM_DEBUG 
-#ifdef	ITEM_DEBUG
+#ifdef	NETGRAPH_DEBUG /*----------------------------------------------*/
 	char *lastfile;
 	int  lastline;
 	TAILQ_ENTRY(ng_item)	  all;		/* all existing items */
-#endif	/* ITEM_DEBUG */
+#endif	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
 };
 #define NGQF_D_M	0x01		/* MASK of data/message */
 #define NGQF_DATA	0x01		/* the queue element is data */
@@ -234,23 +568,6 @@ struct ng_item {
 #define NGQF_FREE	0x04
 
 /*
- * This defines the in-kernel binary interface version.
- * It is possible to change this but leave the external message
- * API the same. Each type also has it's own cookies for versioning as well.
- * Change it for ITEM_DEBUG version so we cannot mix debug and non debug
- * modules.
- */
-#define _NG_ABI_VERSION 5
-#ifdef	ITEM_DEBUG
-#define NG_ABI_VERSION	(_NG_ABI_VERSION + 0x10000)
-#else	/* ITEM_DEBUG */
-#define NG_ABI_VERSION	_NG_ABI_VERSION
-#endif	/* ITEM_DEBUG */
-
-/**********************************************************************
-* Queue item macros.  Peek and extract values.
-**********************************************************************/
-/*
  * Get the mbuf (etc) out of an item.
  * Sets the value in the item to NULL in case we need to call NG_FREE_ITEM()
  * with it, (to avoid freeing the things twice).
@@ -265,13 +582,15 @@ struct ng_item {
 #define _NGI_MSG(i) ((i)->body.msg.msg_msg)
 #define _NGI_RETADDR(i) ((i)->body.msg.msg_retaddr)
 
-#ifdef ITEM_DEBUG
-void	dumpitem(item_p item, char *file, int line);
-static __inline void _ngi_check(item_p item, char *file, int line) ;
-static __inline struct mbuf ** _ngi_m(item_p item, char *file, int line) ;
-static __inline meta_p * _ngi_meta(item_p item, char *file, int line) ;
-static __inline struct ng_mesg ** _ngi_msg(item_p item, char *file, int line) ;
-static __inline ng_ID_t * _ngi_retaddr(item_p item, char *file, int line) ;
+#ifdef NETGRAPH_DEBUG /*----------------------------------------------*/
+void				dumpitem(item_p item, char *file, int line);
+static __inline void		_ngi_check(item_p item, char *file, int line) ;
+static __inline struct mbuf **	_ngi_m(item_p item, char *file, int line) ;
+static __inline meta_p *	_ngi_meta(item_p item, char *file, int line) ;
+static __inline ng_ID_t *	_ngi_retaddr(item_p item, char *file,
+							int line) ;
+static __inline struct ng_mesg **	_ngi_msg(item_p item, char *file,
+							int line) ;
 
 static __inline void
 _ngi_check(item_p item, char *file, int line) 
@@ -312,13 +631,13 @@ _ngi_retaddr(item_p item, char *file, int line)
 	return (&_NGI_RETADDR(item));
 }
 
-#define NGI_M(i) (*_ngi_m(i, __FILE__, __LINE__))
+#define NGI_M(i) (*_ngi_m(i, _NN_))
 
-#define NGI_META(i) (*_ngi_meta(i, __FILE__, __LINE__))
+#define NGI_META(i) (*_ngi_meta(i, _NN_))
 
-#define NGI_MSG(i) (*_ngi_msg(i, __FILE__, __LINE__))
+#define NGI_MSG(i) (*_ngi_msg(i, _NN_))
 
-#define NGI_RETADDR(i) (*_ngi_retaddr(i, __FILE__, __LINE__))
+#define NGI_RETADDR(i) (*_ngi_retaddr(i, _NN_))
 
 #define NGI_GET_M(i,m)							\
 	do {								\
@@ -340,7 +659,7 @@ _ngi_retaddr(item_p item, char *file, int line)
 
 #define NG_FREE_ITEM(item)						\
 	do {								\
-		_ngi_check(item, __FILE__, __LINE__);			\
+		_ngi_check(item, _NN_);					\
 		ng_free_item((item));					\
 	} while (0)
 
@@ -350,8 +669,7 @@ _ngi_retaddr(item_p item, char *file, int line)
 		(item)->lastfile = __FILE__;				\
 	} while (0)
 
-#else	/* ITEM_DEBUG */
-
+#else	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
 
 #define NGI_M(i)	_NGI_M(i)
 #define NGI_META(i)	_NGI_META(i)
@@ -363,14 +681,14 @@ _ngi_retaddr(item_p item, char *file, int line)
 #define NGI_GET_MSG(i,m)     do {m = NGI_MSG(i); NGI_MSG(i) = NULL;  } while (0)
 
 #define	NG_FREE_ITEM(item)	ng_free_item((item))
-#define	SAVE_LINE(item)
+#define	SAVE_LINE(item)		do {} while (0)
 
-#endif	/* ITEM_DEBUG */
+#endif	/* NETGRAPH_DEBUG */ /*----------------------------------------------*/
 	
 /**********************************************************************
 * Data macros.  Send, manipulate and free.
 **********************************************************************/
-/* Send data packet including a possible sync response pointer */
+/* Send previously unpackeged data and metadata. */
 #define NG_SEND_DATA(error, hook, m, meta)				\
 	do {								\
 		item_p item;						\
@@ -387,6 +705,7 @@ _ngi_retaddr(item_p item, char *file, int line)
 		(meta) = NULL;						\
 	} while (0)
 
+/* Send a previously unpackaged mbuf when we have no metadata to send */
 #define NG_SEND_DATA_ONLY(error, hook, m)				\
 	do {								\
 		item_p item;						\
@@ -405,7 +724,10 @@ _ngi_retaddr(item_p item, char *file, int line)
 /*
  * Forward a data packet with no new meta-data.
  * old metadata is passed along without change.
- * Mbuf pointer is updated to new value.
+ * Mbuf pointer is updated to new value. We presume you dealt with the
+ * old one when you update it to the new one (or it maybe the old one).
+ * We got a packet and possibly had to modify the mbuf.
+ * You should probably use NGI_GET_M() if you are going to use this too
  */
 #define NG_FWD_NEW_DATA(error, item, hook, m)				\
 	do {								\
@@ -422,7 +744,7 @@ _ngi_retaddr(item_p item, char *file, int line)
 /*
  * Assuming the data is already ok, just set the new address and send
  */
-#define NG_FWD_DATA(error, item, hook)					\
+#define NG_FWD_ITEM_HOOK(error, item, hook)				\
 	do {								\
 		if (!((error) = ng_address_hook(NULL, (item),		\
 						(hook), NULL))) {	\
@@ -462,12 +784,7 @@ _ngi_retaddr(item_p item, char *file, int line)
 			(m) = NULL;					\
 		}							\
 	} while (0)
-/* Free any data packet and/or meta-data */
-#define NG_FREE_DATAX(m, meta)						\
-	do {								\
-		NG_FREE_M((m));						\
-		NG_FREE_META((meta));					\
-	} while (0)
+
 /*****************************************
 * Message macros
 *****************************************/
@@ -475,13 +792,15 @@ _ngi_retaddr(item_p item, char *file, int line)
 #define NG_SEND_MSG_HOOK(error, here, msg, hook, retaddr)		\
 	do {								\
 		item_p item;						\
-		if ((item = ng_package_msg(msg))			\
-		&& (ng_address_hook((here), (item),			\
-					(hook), (retaddr)) == 0)) {	\
+		if ((item = ng_package_msg(msg)) == NULL) {		\
+			(msg) = NULL;					\
+			(error) = ENOMEM;				\
+			break;						\
+		}							\
+		if (((error) = ng_address_hook((here), (item),		\
+					(hook), (retaddr))) == 0) {	\
 			SAVE_LINE(item);				\
 			(error) = ng_snd_item((item), 0);		\
-		} else {						\
-			(error) = EINVAL;				\
 		}							\
 		(msg) = NULL;						\
 	} while (0)
@@ -489,13 +808,15 @@ _ngi_retaddr(item_p item, char *file, int line)
 #define NG_SEND_MSG_PATH(error, here, msg, path, retaddr)		\
 	do {								\
 		item_p item;						\
-		if ((item = ng_package_msg(msg))			\
-		&& (ng_address_path((here), (item),			\
-					(path), (retaddr)) == 0)) {	\
+		if ((item = ng_package_msg(msg)) == NULL) {		\
+			(msg) = NULL;					\
+			(error) = ENOMEM;				\
+			break;						\
+		}							\
+		if (((error) = ng_address_path((here), (item),		\
+					(path), (retaddr))) == 0) {	\
 			SAVE_LINE(item);				\
 			(error) = ng_snd_item((item), 0);		\
-		} else {						\
-			(error) = EINVAL;				\
 		}							\
 		(msg) = NULL;						\
 	} while (0)
@@ -503,13 +824,15 @@ _ngi_retaddr(item_p item, char *file, int line)
 #define NG_SEND_MSG_ID(error, here, msg, ID, retaddr)			\
 	do {								\
 		item_p item;						\
-		if ((item = ng_package_msg(msg))			\
-		&& (ng_address_ID((here), (item),			\
-					(ID), (retaddr)) == 0)) {	\
+		if ((item = ng_package_msg(msg)) == NULL) {		\
+			(msg) = NULL;					\
+			(error) = ENOMEM;				\
+			break;						\
+		}							\
+		if (((error) = ng_address_ID((here), (item),		\
+					(ID), (retaddr))) == 0) {	\
 			SAVE_LINE(item);				\
 			(error) = ng_snd_item((item), 0);		\
-		} else {						\
-			(error) = EINVAL;				\
 		}							\
 		(msg) = NULL;						\
 	} while (0)
@@ -517,13 +840,15 @@ _ngi_retaddr(item_p item, char *file, int line)
 #define NG_QUEUE_MSG(error, here, msg, path, retaddr)			\
 	do {								\
 		item_p item;						\
-		if ((item = ng_package_msg(msg))			\
-		&& (ng_address_path((here), (item),			\
-					(path), (retaddr)) == 0)) {	\
+		if ((item = ng_package_msg(msg)) == NULL) {		\
+			(msg) = NULL;					\
+			(error) = ENOMEM;				\
+			break;						\
+		}							\
+		if (((error) = ng_address_path((here), (item),		\
+					(path), (retaddr))) == 0) {	\
 			SAVE_LINE(item);				\
-			(error) = ng_snd_item((item), 0);		\
-		} else {						\
-			(error) = EINVAL;				\
+			(error) = ng_snd_item((item), 1);		\
 		}							\
 		(msg) = NULL;						\
 	} while (0)
@@ -535,12 +860,10 @@ _ngi_retaddr(item_p item, char *file, int line)
  */
 #define NG_FWD_MSG_HOOK(error, here, item, hook, retaddr)		\
 	do {								\
-		if ((ng_address_hook((here), (item),			\
+		if (((error) = ng_address_hook((here), (item),		\
 					(hook), (retaddr))) == 0) {	\
 			SAVE_LINE(item);				\
 			(error) = ng_snd_item((item), 0);		\
-		} else {						\
-			(error) = EINVAL;				\
 		}							\
 		(item) = NULL;						\
 	} while (0)
@@ -569,6 +892,72 @@ _ngi_retaddr(item_p item, char *file, int line)
 	} while (0)
 
 
+/***********************************************************************
+ ******** Structures Definitions and Macros for defining a node  *******
+ ***********************************************************************
+ * 
+ * Here we define the structures needed to actually define a new node
+ * type.
+ */
+
+/* node method definitions */
+typedef	int	ng_constructor_t(node_p node);
+typedef	int	ng_rcvmsg_t(node_p node, item_p item, hook_p lasthook);
+typedef	int	ng_shutdown_t(node_p node);
+typedef	int	ng_newhook_t(node_p node, hook_p hook, const char *name);
+typedef	hook_p	ng_findhook_t(node_p node, const char *name);
+typedef	int	ng_connect_t(hook_p hook);
+typedef	int	ng_rcvdata_t(hook_p hook, item_p item);
+typedef	int	ng_disconnect_t(hook_p hook);
+typedef	int	ng_rcvitem (node_p node, hook_p hook, item_p item);
+/*
+ * Command list -- each node type specifies the command that it knows
+ * how to convert between ASCII and binary using an array of these.
+ * The last element in the array must be a terminator with cookie=0.
+ */
+
+struct ng_cmdlist {
+	u_int32_t			cookie;		/* command typecookie */
+	int				cmd;		/* command number */
+	const char			*name;		/* command name */
+	const struct ng_parse_type	*mesgType;	/* args if !NGF_RESP */
+	const struct ng_parse_type	*respType;	/* args if NGF_RESP */
+};
+
+/*
+ * Structure of a node type
+ * If data is sent to the "rcvdata()" entrypoint then the system
+ * may decide to defer it until later by queing it with the normal netgraph
+ * input queuing system.  This is decidde by the HK_QUEUE flag being set in
+ * the flags word of the peer (receiving) hook. The dequeuing mechanism will
+ * ensure it is not requeued again.
+ * Note the input queueing system is to allow modules
+ * to 'release the stack' or to pass data across spl layers.
+ * The data will be redelivered as soon as the NETISR code runs
+ * which may be almost immediatly.  A node may also do it's own queueing
+ * for other reasons (e.g. device output queuing).
+ */
+struct ng_type {
+
+	u_int32_t	version; 	/* must equal NG_API_VERSION */
+	const char	*name;		/* Unique type name */
+	modeventhand_t	mod_event;	/* Module event handler (optional) */
+	ng_constructor_t *constructor;	/* Node constructor */
+	ng_rcvmsg_t	*rcvmsg;	/* control messages come here */
+	ng_shutdown_t	*shutdown;	/* reset, and free resources */
+	ng_newhook_t	*newhook;	/* first notification of new hook */
+	ng_findhook_t	*findhook;	/* only if you have lots of hooks */
+	ng_connect_t	*connect;	/* final notification of new hook */
+	ng_rcvdata_t	*rcvdata;	/* data comes here */
+	ng_disconnect_t	*disconnect;	/* notify on disconnect */
+
+	const struct	ng_cmdlist *cmdlist;	/* commands we can convert */
+
+	/* R/W data private to the base netgraph code DON'T TOUCH! */
+	LIST_ENTRY(ng_type) types;		/* linked list of all types */
+	int		    refs;		/* number of instances */
+};
+
 /*
  * Use the NETGRAPH_INIT() macro to link a node type into the
  * netgraph system. This works for types compiled into the kernel
@@ -601,17 +990,17 @@ MALLOC_DECLARE(M_NETGRAPH_META);
 
 
 
-/* Methods that should go away (or become private)*/
-/* Methods that should exist */
+/*
+ * Methods that the nodes can use.
+ * Many of these methods should usually NOT be used directly but via 
+ * Macros above.
+ */
 int	ng_address_ID(node_p here, item_p item, ng_ID_t ID, ng_ID_t retaddr);
 int	ng_address_hook(node_p here, item_p item, hook_p hook, ng_ID_t retaddr);
-int	ng_address_path(node_p here, item_p item,
-	char *address, ng_ID_t retaddr);
+int	ng_address_path(node_p here, item_p item, char *address, ng_ID_t raddr);
 meta_p	ng_copy_meta(meta_p meta);
 hook_p	ng_findhook(node_p node, const char *name);
-void	ng_free_item(item_p item);
 int	ng_make_node_common(struct ng_type *typep, node_p *nodep);
-int	ng_mod_event(module_t mod, int what, void *arg);
 int	ng_name_node(node_p node, const char *name);
 int	ng_newtype(struct ng_type *tp);
 ng_ID_t ng_node2ID(node_p node);
@@ -621,8 +1010,12 @@ item_p	ng_package_msg_self(node_p here, hook_p hook, struct ng_mesg *msg);
 void	ng_replace_retaddr(node_p here, item_p item, ng_ID_t retaddr);
 int	ng_rmnode_self(node_p here);
 int	ng_snd_item(item_p item, int queue);
-void	ng_unname(node_p node);
-void	ng_unref(node_p node);
+
+/*
+ * prototypes the user should DEFINITLY not use directly
+ */
+void	ng_free_item(item_p item); /* Use NG_FREE_ITEM instead */
+int	ng_mod_event(module_t mod, int what, void *arg);
 
 #endif /* _NETGRAPH_NETGRAPH_H_ */