diff -Nru --exclude .depend --exclude *.o --exclude *.ver --exclude .*.flags --exclude *.orig --exclude *.rej --exclude *~ linuxppc-041202-nfpom1101/net/ipv4/netfilter/ip_conntrack_core.c linuxppc-041202-nfpom1101-docbook/net/ipv4/netfilter/ip_conntrack_core.c
--- linuxppc-041202-nfpom1101/net/ipv4/netfilter/ip_conntrack_core.c	Sat Jan 11 20:32:42 2003
+++ linuxppc-041202-nfpom1101-docbook/net/ipv4/netfilter/ip_conntrack_core.c	Sat Jan 11 21:05:34 2003
@@ -4,6 +4,7 @@
 
 /* (c) 1999 Paul `Rusty' Russell.  Licenced under the GNU General
  * Public Licence. 
+ * (C) 2000-2003 by the netfilter core team <coreteam@netfilter.org>
  *
  * 23 Apr 2001: Harald Welte <laforge@gnumonks.org>
  * 	- new API and handling of conntrack/nat helpers
@@ -11,6 +12,8 @@
  * 16 Jul 2002: Harald Welte <laforge@gnumonks.org>
  * 	- add usage/reference counts to ip_conntrack_expect
  *	- export ip_conntrack[_expect]_{find_get,put} functions
+ * 05 Aug 2002: Harald Welte <laforge@gnumonks.org>
+ * 	- added DocBook-style comments for public API
  * */
 
 #include <linux/version.h>
@@ -87,6 +90,10 @@
 	return p;
 }
 
+/**
+ * ip_ct_find_proto - Find layer 4 protocol helper for given protocol number
+ * @protocol: protocol number
+ */
 struct ip_conntrack_protocol *ip_ct_find_proto(u_int8_t protocol)
 {
 	struct ip_conntrack_protocol *p;
@@ -382,7 +389,14 @@
 	return h;
 }
 
-/* Find a connection corresponding to a tuple. */
+/**
+ * ip_conntrack_find_get - find conntrack according to tuple
+ * @tuple: conntrack tuple for which we search conntrack
+ * @ignored_conntrack: ignore this conntrack during search
+ *
+ * This function increments the reference count of the found
+ * conntrack (if any).
+ */
 struct ip_conntrack_tuple_hash *
 ip_conntrack_find_get(const struct ip_conntrack_tuple *tuple,
 		      const struct ip_conntrack *ignored_conntrack)
@@ -410,7 +424,14 @@
 	return ct;
 }
 
-/* Return conntrack and conntrack_info given skb->nfct->master */
+/**
+ * ip_conntrack_get - Return conntrack and conntrack_info for given skb
+ * @skb: skb for which we want to find conntrack and conntrack_info
+ * @ctinfo: pointer to ctinfo, used as return value
+ *
+ * This function resolves the respective conntrack and conntrack_info
+ * structures for the connection this packet (skb) is part of.
+ */
 struct ip_conntrack *
 ip_conntrack_get(struct sk_buff *skb, enum ip_conntrack_info *ctinfo)
 {
@@ -479,8 +500,14 @@
 	return NF_DROP;
 }
 
-/* Returns true if a connection correspondings to the tuple (required
-   for NAT). */
+/**
+ * ip_conntrack_tuple_taken - Find out if tuple is already in use
+ * @tuple: tuple to be used for this test
+ * @ignored_conntrack: conntrack which is excluded from result
+ *
+ * This function is called by the NAT code in order to find out if
+ * a particular tuple is already in use by some connection.
+ */
 int
 ip_conntrack_tuple_taken(const struct ip_conntrack_tuple *tuple,
 			 const struct ip_conntrack *ignored_conntrack)
@@ -620,7 +647,13 @@
 {
 	return ip_ct_tuple_mask_cmp(rtuple, &i->tuple, &i->mask);
 }
-
+/**
+ * ip_ct_find_helper - Find application helper according to tuple
+ * @tuple: tuple for which helper needs to be found
+ *
+ * This function is used to determine if any registered conntrack helper
+ * is to be used for the given tuple.
+ */
 struct ip_conntrack_helper *ip_ct_find_helper(const struct ip_conntrack_tuple *tuple)
 {
 	return LIST_FIND(&helpers, helper_cmp,
@@ -911,6 +944,14 @@
 	return ip_ct_tuple_mask_cmp(&i->tuple, tuple, &intersect_mask);
 }
 
+/**
+ * ip_conntrack_unexpect_related - Unexpect a related connection
+ * @expect: expecattin to be removed
+ *
+ * This function removes an existing expectation, that has not yet been
+ * confirmed (i.e. expectation was issued, but expected connection didn't
+ * arrive yet)
+ */
 inline void ip_conntrack_unexpect_related(struct ip_conntrack_expect *expect)
 {
 	WRITE_LOCK(&ip_conntrack_lock);
@@ -928,7 +969,20 @@
 	WRITE_UNLOCK(&ip_conntrack_lock);
 }
 
-/* Add a related connection. */
+/**
+ * ip_conntrack_expect_related - Expect a related connection
+ * @related_to: master conntrack
+ * @expect: expectation with all values filled in
+ *
+ * This function is called by conntrack application helpers who
+ * have detected that the control (master) connection is just about
+ * to negotiate a related slave connection. 
+ *
+ * Note: This function allocates it's own struct ip_conntrack_expect,
+ * copying the values from the 'expect' parameter.  Thus, 'expect' can
+ * be allocated on the stack and does not need to be valid after this
+ * function returns.
+ */
 int ip_conntrack_expect_related(struct ip_conntrack *related_to,
 				struct ip_conntrack_expect *expect)
 {
@@ -1065,7 +1119,15 @@
 	return ret;
 }
 
-/* Change tuple in an existing expectation */
+/**
+ * ip_conntrack_change_expect - Change tuple in existing expectation
+ * @expect: expectation which is to be changed
+ * @newtuple: new tuple for expect
+ *
+ * This function is mostly called by NAT application helpers, who want to
+ * change an expectation issued by their respective conntrack application
+ * helper counterpart.
+ */
 int ip_conntrack_change_expect(struct ip_conntrack_expect *expect,
 			       struct ip_conntrack_tuple *newtuple)
 {
@@ -1105,8 +1167,15 @@
 	return ret;
 }
 
-/* Alter reply tuple (maybe alter helper).  If it's already taken,
-   return 0 and don't do alteration. */
+/**
+ * ip_conntrack_alter_reply - Alter reply tuple of conntrack
+ * @conntrack: conntrack whose reply tuple we want to alter
+ * @newreply: designated reply tuple for this conntrack
+ *
+ * This function alters the reply tuple of a conntrack to the given
+ * newreply tuple.  If this newreply tuple is already taken, return 0
+ * and don't do alteration
+ */
 int ip_conntrack_alter_reply(struct ip_conntrack *conntrack,
 			     const struct ip_conntrack_tuple *newreply)
 {
@@ -1131,6 +1200,13 @@
 	return 1;
 }
 
+/**
+ * ip_conntrack_helper_register - Register a conntrack application helper
+ * @me: structure describing the helper
+ *
+ * This function is called by conntrack application helpers to register
+ * themselves with the conntrack core.
+ */
 int ip_conntrack_helper_register(struct ip_conntrack_helper *me)
 {
 	MOD_INC_USE_COUNT;
@@ -1154,6 +1230,13 @@
 	return 0;
 }
 
+/**
+ * ip_conntrack_helper_unregister - Unregister a conntrack application helper
+ * @me: structure describing the helper
+ *
+ * This function is called by conntrack application helpers to unregister
+ * themselvers from the conntrack core.
+ */
 void ip_conntrack_helper_unregister(struct ip_conntrack_helper *me)
 {
 	unsigned int i;
@@ -1175,7 +1258,14 @@
 	MOD_DEC_USE_COUNT;
 }
 
-/* Refresh conntrack for this many jiffies. */
+/**
+ * ip_ct_refresh - Refresh conntrack timer for given conntrack
+ * @ct: conntrack which we want to refresh
+ * @extra_jiffies: number of jiffies to add
+ *
+ * This function is called by protocol helpers and application helpers in
+ * order to change the expiration timer of a conntrack entry.
+ */
 void ip_ct_refresh(struct ip_conntrack *ct, unsigned long extra_jiffies)
 {
 	IP_NF_ASSERT(ct->timeout.data == (unsigned long)ct);
@@ -1194,7 +1284,16 @@
 	WRITE_UNLOCK(&ip_conntrack_lock);
 }
 
-/* Returns new sk_buff, or NULL */
+
+/**
+ * ip_ct_gather_frags - Gather fragments of a particular skb
+ * @skb: pointer to sk_buff of fragmented IP packet
+ *
+ * This code is just a wrapper around the defragmentation code in the core IPv4
+ * stack.  It also takes care of nonlinear skb's.
+ *
+ * Returns new sk_buff, or NULL
+ */
 struct sk_buff *
 ip_ct_gather_frags(struct sk_buff *skb)
 {
@@ -1282,6 +1381,16 @@
 	return h;
 }
 
+/**
+ * ip_ct_selective_cleanup - Selectively delete a set of conntrack entries
+ * @kill: callback function selecting which entries to delete
+ * @data: opaque data pointer, becomes 2nd argument for kill function
+ *
+ * This function can be used to selectively delete elements of the conntrack
+ * hashtable.  The function iterates over the list of conntrack entries and
+ * calls the 'kill' function for every entry.  If the return value is true,
+ * the connection is deleted (death_by_timeout).
+ */
 void
 ip_ct_selective_cleanup(int (*kill)(const struct ip_conntrack *i, void *data),
 			void *data)
diff -Nru --exclude .depend --exclude *.o --exclude *.ver --exclude .*.flags --exclude *.orig --exclude *.rej --exclude *~ linuxppc-041202-nfpom1101/net/ipv4/netfilter/ip_conntrack_standalone.c linuxppc-041202-nfpom1101-docbook/net/ipv4/netfilter/ip_conntrack_standalone.c
--- linuxppc-041202-nfpom1101/net/ipv4/netfilter/ip_conntrack_standalone.c	Tue Dec  3 18:30:05 2002
+++ linuxppc-041202-nfpom1101-docbook/net/ipv4/netfilter/ip_conntrack_standalone.c	Sat Jan 11 21:01:51 2003
@@ -293,13 +293,20 @@
 	return ret;
 }
 
-/* FIXME: Allow NULL functions and sub in pointers to generic for
-   them. --RR */
+/**
+ * ip_conntrack_protocol_register - Register layer 4 protocol helper
+ * @proto: structure describing this layer 4 protocol helper
+ *
+ * This function is called by layer 4 protocol helpers to register 
+ * themselves with the conntrack core.
+ */
 int ip_conntrack_protocol_register(struct ip_conntrack_protocol *proto)
 {
 	int ret = 0;
 	struct list_head *i;
 
+	/* FIXME: Allow NULL functions and sub in pointers to generic for
+	   them. --RR */
 	WRITE_LOCK(&ip_conntrack_lock);
 	for (i = protocol_list.next; i != &protocol_list; i = i->next) {
 		if (((struct ip_conntrack_protocol *)i)->proto
@@ -317,12 +324,20 @@
 	return ret;
 }
 
+/**
+ * ip_conntrack_protocol_unregister - Unregister layer 4 protocol helper
+ * @proto: structure describing this layer 4 protocol helper
+ *
+ * This function is called byh layer 4 protocol helpers to unregister
+ * themselvers from the conntrack core.  Please note that all conntrack
+ * entries for this protocol are deleted from the conntrack hash table.
+ */
 void ip_conntrack_protocol_unregister(struct ip_conntrack_protocol *proto)
 {
 	WRITE_LOCK(&ip_conntrack_lock);
 
-	/* ip_ct_find_proto() returns proto_generic in case there is no protocol 
-	 * helper. So this should be enough - HW */
+	/* ip_ct_find_proto() returns proto_generic in case there is no
+	 * protocol helper. So this should be enough - HW */
 	LIST_DELETE(&protocol_list, proto);
 	WRITE_UNLOCK(&ip_conntrack_lock);
 	
diff -Nru --exclude .depend --exclude *.o --exclude *.ver --exclude .*.flags --exclude *.orig --exclude *.rej --exclude *~ linuxppc-041202-nfpom1101/net/ipv4/netfilter/ip_nat_core.c linuxppc-041202-nfpom1101-docbook/net/ipv4/netfilter/ip_nat_core.c
--- linuxppc-041202-nfpom1101/net/ipv4/netfilter/ip_nat_core.c	Sat Jan 11 20:32:42 2003
+++ linuxppc-041202-nfpom1101-docbook/net/ipv4/netfilter/ip_nat_core.c	Sat Jan 11 21:01:51 2003
@@ -1,7 +1,9 @@
 /* NAT for netfilter; shared with compatibility layer. */
 
 /* (c) 1999 Paul `Rusty' Russell.  Licenced under the GNU General
-   Public Licence. */
+ * Public Licence. 
+ * (c) 2000-2002 by the netfilter core team <coreteam@netfilter.org>
+ */
 #include <linux/version.h>
 #include <linux/module.h>
 #include <linux/types.h>
@@ -95,9 +97,16 @@
 	WRITE_UNLOCK(&ip_nat_lock);
 }
 
-/* We do checksum mangling, so if they were wrong before they're still
- * wrong.  Also works for incomplete packets (eg. ICMP dest
- * unreachables.) */
+/**
+ * ip_nat_cheat_check - Incremental checksum change for IP/TCP checksum
+ * @oldvalinv: bit-inverted old value of 32bit word
+ * @newval: new value of 32bit word
+ * @oldcheck: old checksum value
+ *
+ * This function implements incremental checksum mangling, so if a checksum
+ * was wrong it will still be wrong after mangling.  Also works for incomplete
+ * packets (eg. ICMP dest unreachables).  Return value is the new checksum.
+ */
 u_int16_t
 ip_nat_cheat_check(u_int32_t oldvalinv, u_int32_t newval, u_int16_t oldcheck)
 {
@@ -123,7 +132,14 @@
 	return i;
 }
 
-/* Is this tuple already taken? (not by us) */
+/**
+ * ip_nat_used_tuple - Is this tuple already in use?
+ * @tuple: tuple to be used for this check
+ * @ignored_conntrack: conntrack excluded from this check
+ *
+ * This function checks for the reply (inverted) tuple in the conntrack
+ * hash.  This is necessarry with NAT, since there is no fixed mapping.
+ */
 int
 ip_nat_used_tuple(const struct ip_conntrack_tuple *tuple,
 		  const struct ip_conntrack *ignored_conntrack)
@@ -511,6 +527,19 @@
 #endif
 };
 
+/**
+ * ip_nat_setup_info - Set up NAT mappings for NEW packet
+ * @conntrack: conntrack on which we operate
+ * @mr: address/port range which is valid for this NAT mapping
+ * @hooknum: hook at which this NAT mapping applies
+ *
+ * This function is called by NAT targets (SNAT,DNAT,...) and by
+ * the NAT application helper modules.  It is called for the NEW packet
+ * of a connection in order to specify which NAT mappings shall apply to
+ * this connection at a given hook.
+ *
+ * Note: The reply mappings are created automagically by this function. 
+ */
 unsigned int
 ip_nat_setup_info(struct ip_conntrack *conntrack,
 		  const struct ip_nat_multi_range *mr,
diff -Nru --exclude .depend --exclude *.o --exclude *.ver --exclude .*.flags --exclude *.orig --exclude *.rej --exclude *~ linuxppc-041202-nfpom1101/net/ipv4/netfilter/ip_nat_helper.c linuxppc-041202-nfpom1101-docbook/net/ipv4/netfilter/ip_nat_helper.c
--- linuxppc-041202-nfpom1101/net/ipv4/netfilter/ip_nat_helper.c	Sat Jan 11 20:28:11 2003
+++ linuxppc-041202-nfpom1101-docbook/net/ipv4/netfilter/ip_nat_helper.c	Sat Jan 11 21:11:42 2003
@@ -114,9 +114,19 @@
 }
 
 
-/* Generic function for mangling variable-length address changes inside
- * NATed TCP connections (like the PORT XXX,XXX,XXX,XXX,XXX,XXX
- * command in FTP).
+/**
+ * ip_nat_mangle_tcp_packet - Mangle and potentially resize payload packet
+ * @skb: pointer to skb of packet on which we operate
+ * @ct: conntrack of the connection to which this packet belongs
+ * @ctinfo: conntrack_info of the connection to which this packet belongs
+ * @match_offset: offset in bytes where to-be-manipulated part starts
+ * @match_len: lenght of the to-be-manipulated part
+ * @rep_buffer: pointer to buffer containing replacement
+ * @rep_len: length of replacement
+ *
+ * Generic function for mangling fixed and variable-length changes inside
+ * NATed TCP connections (like the PORT XXX,XXX,XXX,XXX,XXX,XXX command 
+ * in FTP).
  *
  * Takes care about all the nasty sequence number changes, checksumming,
  * skb enlargement, ...
@@ -211,16 +221,27 @@
 	return 1;
 }
 			
-/* Generic function for mangling variable-length address changes inside
- * NATed UDP connections (like the CONNECT DATA XXXXX MESG XXXXX INDEX XXXXX
- * command in the Amanda protocol)
+/**
+ * ip_nat_mangle_udp_packet - Mangle and potentially resize payload packet
+ * @skb: pointer to skb of packet on which we operate
+ * @ct: conntrack of the connection to which this packet belongs
+ * @ctinfo: conntrack_info of the connection to which this packet belongs
+ * @match_offset: offset in bytes where to-be-manipulated part starts
+ * @match_len: lenght of the to-be-manipulated part
+ * @rep_buffer: pointer to buffer containing replacement
+ * @rep_len: length of replacement
+ *
+ * Generic function for mangling fixed and variable-length changes inside
+ * NATed TCP connections (like the CONNECT DATA XXXXX MESG XXXXX INDEX XXXXX
+ * commad in the Amanda protocol)
  *
  * Takes care about all the nasty sequence number changes, checksumming,
  * skb enlargement, ...
  *
- * XXX - This function could be merged with ip_nat_mangle_tcp_packet which
- *       should be fairly easy to do.
- */
+ * FIXME: should be unified with ip_nat_mangle_tcp_packet!!
+ *
+ * */
+
 int 
 ip_nat_mangle_udp_packet(struct sk_buff **skb,
 			 struct ip_conntrack *ct,
@@ -474,6 +495,13 @@
 
 #define MODULE_MAX_NAMELEN		32
 
+/**
+ * ip_nat_helper_register - Register NAT application helper
+ * @me: structure describing the helper
+ *
+ * This function is called by NAT application helpers to register
+ * themselves with the NAT core.
+ */
 int ip_nat_helper_register(struct ip_nat_helper *me)
 {
 	int ret = 0;
@@ -541,6 +569,13 @@
 	return ret;
 }
 
+/**
+ * ip_nat_helper_unregister - Unregister NAT application helper
+ * @me: structure describing the helper
+ *
+ * This function is called by NAT application helpers to unregister
+ * themselves from the NAT core.
+ */
 void ip_nat_helper_unregister(struct ip_nat_helper *me)
 {
 	int found = 0;
diff -Nru --exclude .depend --exclude *.o --exclude *.ver --exclude .*.flags --exclude *.orig --exclude *.rej --exclude *~ linuxppc-041202-nfpom1101/net/ipv4/netfilter/ip_nat_standalone.c linuxppc-041202-nfpom1101-docbook/net/ipv4/netfilter/ip_nat_standalone.c
--- linuxppc-041202-nfpom1101/net/ipv4/netfilter/ip_nat_standalone.c	Sat Jan 11 20:28:11 2003
+++ linuxppc-041202-nfpom1101-docbook/net/ipv4/netfilter/ip_nat_standalone.c	Sat Jan 11 21:01:51 2003
@@ -238,7 +238,13 @@
 = { { NULL, NULL }, ip_nat_fn, PF_INET, NF_IP_LOCAL_IN, NF_IP_PRI_NAT_SRC };
 #endif
 
-/* Protocol registration. */
+/**
+ * ip_nat_protocol_register - Register a layer 4 protocol helper
+ * @proto: structure describing this helper
+ * 
+ * This function is called by NAT layer 4 protocol helpers to register
+ * themselvers with the NAT core.
+ */
 int ip_nat_protocol_register(struct ip_nat_protocol *proto)
 {
 	int ret = 0;
@@ -261,9 +267,16 @@
 	return ret;
 }
 
-/* Noone stores the protocol anywhere; simply delete it. */
+/**
+ * ip_nat_protocol_unregister - Unregister a layer 4 protocol helper
+ * @proto: sturcture describing the helper
+ *
+ * This function is called by NAT layer 4 protocol helpers to
+ * unregister themselves from the NAT core.
+ */
 void ip_nat_protocol_unregister(struct ip_nat_protocol *proto)
 {
+	/* Noone stores the protocol anywhere; simply delete it. */
 	WRITE_LOCK(&ip_nat_lock);
 	LIST_DELETE(&protos, proto);
 	WRITE_UNLOCK(&ip_nat_lock);
--- linuxppc-041202-nfpom1101/net/core/netfilter.c	Tue Dec  3 18:33:21 2002
+++ linuxppc-041202-nfpom1101-docbook/net/core/netfilter.c	Sat Jan 11 21:01:51 2003
@@ -57,6 +57,10 @@
 	void *data;
 } queue_handler[NPROTO];
 
+/**
+ * nf_register_hook - Register with a netfilter hook
+ * @reg: Hook operations to be registered
+ */
 int nf_register_hook(struct nf_hook_ops *reg)
 {
 	struct list_head *i;
@@ -73,6 +77,10 @@
 	return 0;
 }
 
+/**
+ * nf_unregister_hook - Unregister from a netfilter hook
+ * @reg: hook operations to be unregistered
+ */
 void nf_unregister_hook(struct nf_hook_ops *reg)
 {
 	br_write_lock_bh(BR_NETPROTO_LOCK);
@@ -373,6 +381,18 @@
 	return NF_ACCEPT;
 }
 
+/**
+ * nf_register_queue_handler - Registere a queue handler with netfilter
+ * @pf: protocol family
+ * @outfn: function called by core to enqueue a packet
+ * @data: opaque parameter, passed through
+ *
+ * This function registers a queue handler with netfilter.  There can only
+ * be one queue handler for every protocol family.
+ *
+ * A queue handler _must_ reinject every packet via nf_reinject, no
+ * matter what.
+ */
 int nf_register_queue_handler(int pf, nf_queue_outfn_t outfn, void *data)
 {      
 	int ret;
@@ -390,7 +410,12 @@
 	return ret;
 }
 
-/* The caller must flush their queue before this */
+/**
+ * nf_unregister_queue_handler - Unregister queue handler from netfilter
+ * @pf: protocol family
+ *
+ * The caller must flush their queue before unregistering
+ */
 int nf_unregister_queue_handler(int pf)
 {
 	br_write_lock_bh(BR_NETPROTO_LOCK);
@@ -502,6 +527,15 @@
 	return ret;
 }
 
+/**
+ * nf_reinject - Reinject a packet from a queue handler
+ * @skb: the packet to be reinjected
+ * @info: info which was passed to the outfn() of the queue handler
+ * @verdict: verdict (NF_ACCEPT, ...) for this packet
+ *
+ * This is the function called by a queue handler to reinject a
+ * packet.
+ */
 void nf_reinject(struct sk_buff *skb, struct nf_info *info,
 		 unsigned int verdict)
 {
