svn commit: r195290 - projects/mesh11s/sys/net80211

[Sam Leffler]

Author: sam
Date: Thu Jul  2 15:59:32 2009
New Revision: 195290
URL: http://svn.freebsd.org/changeset/base/195290

Log:
  add comments

Modified:
  projects/mesh11s/sys/net80211/ieee80211_ageq.c

Modified: projects/mesh11s/sys/net80211/ieee80211_ageq.c
==============================================================================
--- projects/mesh11s/sys/net80211/ieee80211_ageq.c	Thu Jul  2 15:49:28 2009	(r195289)
+++ projects/mesh11s/sys/net80211/ieee80211_ageq.c	Thu Jul  2 15:59:32 2009	(r195290)
@@ -43,14 +43,21 @@ __FBSDID("$FreeBSD$");
 
 #include <net80211/ieee80211_var.h>
 
+/*
+ * Initialize an ageq.
+ */
 void
 ieee80211_ageq_init(struct ieee80211_ageq *aq, int maxlen, const char *name)
 {
 	memset(aq, 0, sizeof(aq));
 	aq->aq_maxlen = maxlen;
-	IEEE80211_AGEQ_INIT(aq, name);	/* OS-dependent setup */
+	IEEE80211_AGEQ_INIT(aq, name);		/* OS-dependent setup */
 }
 
+/*
+ * Cleanup an ageq initialized with ieee80211_ageq_init.  Note
+ * the queue is assumed empty; this can be done with ieee80211_ageq_drain.
+ */
 void
 ieee80211_ageq_cleanup(struct ieee80211_ageq *aq)
 {
@@ -58,6 +65,11 @@ ieee80211_ageq_cleanup(struct ieee80211_
 	IEEE80211_AGEQ_DESTROY(aq);		/* OS-dependent cleanup */
 }
 
+/*
+ * Free an mbuf according to ageq rules: if marked as holding
+ * and 802.11 frame then also reclaim a node reference from
+ * the packet header; this handles packets q'd in the tx path.
+ */
 static void
 ageq_mfree(struct mbuf *m)
 {
@@ -69,6 +81,9 @@ ageq_mfree(struct mbuf *m)
 	m_freem(m);
 }
 
+/*
+ * Free a list of mbufs using ageq rules (see above).
+ */
 void
 ieee80211_ageq_mfree(struct mbuf *m)
 {
@@ -80,6 +95,11 @@ ieee80211_ageq_mfree(struct mbuf *m)
 	}
 }
 
+/*
+ * Append an mbuf to the ageq and mark it with the specified max age
+ * If the frame is not removed before the age (in seconds) expires
+ * then it is reclaimed (along with any node reference).
+ */
 int
 ieee80211_ageq_append(struct ieee80211_ageq *aq, struct mbuf *m, int age)
 {
@@ -110,12 +130,18 @@ ieee80211_ageq_append(struct ieee80211_a
 	}
 }
 
+/*
+ * Drain/reclaim all frames from an ageq.
+ */
 void
 ieee80211_ageq_drain(struct ieee80211_ageq *aq)
 {
 	ieee80211_ageq_mfree(ieee80211_ageq_remove(aq, NULL));
 }
 
+/*
+ * Drain/reclaim frames associated with a specific node from an ageq.
+ */
 void
 ieee80211_ageq_drain_node(struct ieee80211_ageq *aq,
 	struct ieee80211_node *ni)
@@ -124,10 +150,11 @@ ieee80211_ageq_drain_node(struct ieee802
 }
 
 /*
- * Age frames on the stage queue.  We store ages as time
- * deltas so we can check and/or adjust only the head of the list.
- * If a frame's age exceeds the tick then discard it.
- * The number of frames discarded is returned to the caller.
+ * Age frames on the age queue.  Ages are stored as time
+ * deltas (in seconds) so we can check and/or adjust only
+ * the head of the list.  If a frame's age exceeds the time
+ * quanta then remove it.  The list of removed frames is
+ * is returned to the caller joined by m_nextpkt.
  */
 struct mbuf *
 ieee80211_ageq_age(struct ieee80211_ageq *aq, int quanta)
@@ -155,6 +182,10 @@ ieee80211_ageq_age(struct ieee80211_ageq
 	return head;
 }
 
+/*
+ * Remove all frames matching the specified node identifier.
+ * Frames are returned as a list joined by m_nextpkt.
+ */
 struct mbuf *
 ieee80211_ageq_remove(struct ieee80211_ageq *aq,
 	struct ieee80211_node *match)