From: Eric Leblond <eric@regit.org>
Date: Mon, 3 Sep 2012 12:57:44 +0000 (+0200)
Subject: af-packet: add doxygen comments
X-Git-Tag: suricata-1.4beta1~43
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a645726262bb6e87c79e316862f67542cdf42e11;p=thirdparty%2Fsuricata.git

af-packet: add doxygen comments

This patch adds doxygen comments to newly introduced function and adds
module AF_PACKET doxygen module with a dedicated AFP peers module.
---

diff --git a/src/runmode-af-packet.c b/src/runmode-af-packet.c
index d2922e4fa6..56356501d0 100644
--- a/src/runmode-af-packet.c
+++ b/src/runmode-af-packet.c
@@ -15,6 +15,12 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup afppacket
+ *
+ * @{
+ */
+
 /**
  * \file
  *
@@ -507,3 +513,7 @@ int RunModeIdsAFPWorkers(DetectEngineCtx *de_ctx)
 #endif /* HAVE_AF_PACKET */
     SCReturnInt(0);
 }
+
+/**
+ * @}
+ */
diff --git a/src/source-af-packet.c b/src/source-af-packet.c
index 2aaa26eb7f..ac8a45e3ce 100644
--- a/src/source-af-packet.c
+++ b/src/source-af-packet.c
@@ -15,6 +15,12 @@
  * 02110-1301, USA.
  */
 
+/**
+ *  \defgroup afppacket AF_PACKET running mode
+ *
+ *  @{
+ */
+
 /**
  * \file
  *
@@ -218,6 +224,20 @@ void TmModuleReceiveAFPRegister (void) {
     tmm_modules[TMM_RECEIVEAFP].flags = TM_FLAG_RECEIVE_TM;
 }
 
+
+/**
+ *  \defgroup afppeers AFP peers list
+ *
+ * AF_PACKET has an IPS mode were interface are peered: packet from
+ * on interface are sent the peered interface and the other way. The ::AFPPeer
+ * list is maitaining the list of peers. Each ::AFPPeer is storing the needed
+ * information to be able to send packet on the interface.
+ * A element of the list must not be destroyed during the run of Suricata as it
+ * is used by ::Packet and other threads.
+ *
+ *  @{
+ */
+
 typedef struct AFPPeersList_ {
     TAILQ_HEAD(, AFPPeer_) peers; /**< Head of list of fragments. */
     int cnt;
@@ -225,7 +245,11 @@ typedef struct AFPPeersList_ {
 } AFPPeersList;
 
 /**
- * Update the peer.
+ * \brief Update the peer.
+ *
+ * Update the AFPPeer of a thread ie set new state, socket number
+ * or iface index.
+ *
  */
 void AFPPeerUpdate(AFPThreadVars *ptv)
 {
@@ -238,6 +262,9 @@ void AFPPeerUpdate(AFPThreadVars *ptv)
     (void)SC_ATOMIC_SET(ptv->mpeer->state, ptv->afp_state);
 }
 
+/**
+ * \brief Clean and free ressource used by an ::AFPPeer
+ */
 void AFPPeerClean(AFPPeer *peer)
 {
     if (peer->flags & AFP_SOCK_PROTECT)
@@ -251,6 +278,9 @@ void AFPPeerClean(AFPPeer *peer)
 AFPPeersList peerslist;
 
 
+/**
+ * \brief Init the global list of ::AFPPeer
+ */
 TmEcode AFPPeersListInit()
 {
     SCEnter();
@@ -260,6 +290,11 @@ TmEcode AFPPeersListInit()
     SCReturnInt(TM_ECODE_OK);
 }
 
+/**
+ * \brief Check that all ::AFPPeer got a peer
+ *
+ * \retval TM_ECODE_FAILED if some threads are not peered or TM_ECODE_OK else.
+ */
 TmEcode AFPPeersListCheck()
 {
 #define AFP_PEERS_MAX_TRY 4
@@ -278,6 +313,9 @@ TmEcode AFPPeersListCheck()
     SCReturnInt(TM_ECODE_FAILED);
 }
 
+/**
+ * \brief Declare a new AFP thread to AFP peers list.
+ */
 TmEcode AFPPeersListAdd(AFPThreadVars *ptv)
 {
     SCEnter();
@@ -321,6 +359,9 @@ TmEcode AFPPeersListAdd(AFPThreadVars *ptv)
     SCReturnInt(TM_ECODE_OK);
 }
 
+/**
+ * \brief Clean the global peers list.
+ */
 void AFPPeersListClean()
 {
     AFPPeer *pitem;
@@ -331,6 +372,10 @@ void AFPPeersListClean()
     }
 }
 
+/**
+ * @}
+ */
+
 /**
  * \brief Registration Function for DecodeAFP.
  * \todo Unit tests are needed for this module.
@@ -1387,3 +1432,6 @@ TmEcode DecodeAFPThreadInit(ThreadVars *tv, void *initdata, void **data)
 
 #endif /* HAVE_AF_PACKET */
 /* eof */
+/**
+ * @}
+ */
diff --git a/src/source-af-packet.h b/src/source-af-packet.h
index 43bb21df5b..d9e9a759a6 100644
--- a/src/source-af-packet.h
+++ b/src/source-af-packet.h
@@ -74,6 +74,11 @@ typedef struct AFPIfaceConfig_
     void (*DerefFunc)(void *);
 } AFPIfaceConfig;
 
+/**
+ * \ingroup afppeers
+ * @{
+ */
+
 typedef struct AFPPeer_ {
     char iface[AFP_IFACE_NAME_LENGTH];
     SC_ATOMIC_DECLARE(int, socket);
@@ -93,6 +98,9 @@ typedef struct AFPPacketVars_
     AFPPeer *peer;
 } AFPPacketVars;
 
+/**
+ * @}
+ */
 
 void TmModuleReceiveAFPRegister (void);
 void TmModuleDecodeAFPRegister (void);