[hipl-commit] [trunk] Rev 3546: Doxygen for cache_port.c

  • From: Miika Komu <miika@xxxxxx>
  • To: hipl-commit@xxxxxxxxxxxxx
  • Date: Mon, 8 Feb 2010 13:46:23 +0200

Committer: Miika Komu <miika@xxxxxx>
Date: Mon Feb 08 13:46:21 2010 +0200
Revision: 3546
Revision-id: miika@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Branch nick: trunk

Log:
  Doxygen for cache_port.c

Modified:
  D  firewall/cache.c.doxyme
  D  firewall/cache_port.c.doxyme
  M  firewall/cache_port.c

=== removed file 'firewall/cache.c.doxyme'
--- firewall/cache.c.doxyme     2010-02-08 11:13:32 +0000
+++ firewall/cache.c.doxyme     1970-01-01 00:00:00 +0000
@@ -1,92 +0,0 @@
-
-
-
- ///  Single line comment for dOxygen.
-
-/**
- * my_great_function
- *
- * Write description of function here.
- * The function should follow these comments.
- * 
- * Document the use of each function variable and indicate if this
- * argument is used to return information to the calling context. Use
- * [out] for outut parameters (This is very important). Align the 
- * descriptions to improve readability.
- *
- *  @note: put important usage informations to notes. 
- *
- *  @param      firstArg     Description of first function argument.
- *  @param[out] secondArg    Description of second function argument.
- *  @param      thirdArg     Description of third function argument.
- *  @return Description of returned value.
- **/
-
-int my_great_function(int firstArg, char** secondArg, int thirdArg){
-    .....
-
-/// Now it's your turn.
-
-
-
-
-/**
- * firewall_cache_db_match 
- *
- *
- * @param hit_our
- * @param hit_peer
- * @param lsi_our
- * @param lsi_peer
- * @param ip_our
- * @param ip_peer
- * @param state
- * @return 
- **/
-
-
-/**
- * firewall_cache_init_hldb 
- *
- *
- * @param void
- * @return 
- **/
-
-
-/**
- * hip_cache_create_hl_entry 
- *
- *
- * @param void
- * @return 
- **/
-
-
-/**
- * hip_firewall_cache_delete_hldb 
- *
- *
- * @param void
- * @return 
- **/
-
-
-/**
- * hip_firewall_hash_hit_peer 
- *
- *
- * @param ptr
- * @return 
- **/
-
-
-/**
- * hip_firewall_match_hit_peer 
- *
- *
- * @param ptr1
- * @param ptr2
- * @return 
- **/
-

=== modified file 'firewall/cache_port.c'
--- firewall/cache_port.c       2010-01-19 09:28:42 +0000
+++ firewall/cache_port.c       2010-02-08 11:46:21 +0000
@@ -1,3 +1,25 @@
+/**
+ * @file firewall/cache_port.c
+ *
+ * Distributed under <a 
href="http://www.gnu.org/licenses/gpl2.txt";>GNU/GPL</a>.
+ *
+ * Cache TCP and UDP port information for incoming HIP-related connections for 
LSIs.
+ * When hipfw sees an incoming HIT-based connection, it needs to figure out if
+ * it needs to be translated to LSI or not. LSI translation is done only when 
there is
+ * no IPv6 application bound the corresponding TCP or UDP port. The port 
information
+ * can be read from /proc but consumes time. To avoid this overhead, hipfw 
caches
+ * the port information after the first read. Notice that cache is static and 
hipfw
+ * must be restarted if there are changes in the port numbers. This is 
described in
+ * more detail in <a
+ * href="http://hipl.hiit.fi/hipl/thesis_teresa_finez.pdf";>T. Finez,
+ * Backwards Compatibility Experimentation with Host Identity Protocol
+ * and Legacy Software and Networks , final project, December 2008</a>.
+ *
+ * @brief Cache TCP and UDP port numbers for inbound HIP-related connections 
to optimize LSI translation
+ *
+ * @author Miika Komu <miika@xxxxxx>
+ **/
+
 #include "cache_port.h"
 #include "cache.h"
 #include "lib/core/misc.h"
@@ -5,13 +27,12 @@
 static HIP_HASHTABLE *firewall_port_cache_db;
 
 /**
- * port_cache_add_new_entry:
- * Adds a default entry in the firewall port cache.
+ * add a default entry in the firewall port cache.
  * 
- * @param key  self-evident
- * @param value        self-evident
+ * @param key the hash key (a string consisting of concatenation of the port, 
an underscore and the protocol)
+ * @param value        the value for the hash key (LSI mode value)
  *
- * @return     error if any
+ * @return zero on success or non-zero on failure
  */
 static int port_cache_add_new_entry(const char *key, int value){
        firewall_port_cache_hl_t *new_entry = NULL;
@@ -31,8 +52,10 @@
 
 
 /**
- * firewall_port_cache_db_match:
- * Search in the port cache database the key composed of this port and protocol
+ * Search in the port cache database. The key composed of port and protocol
+ *
+ * @param port the TCP or UDP port to search for
+ * @param proto the protocol (IPPROTO_UDP, IPPROTO_TCP or IPPROTO_ICMPV6)
  */
 firewall_port_cache_hl_t *firewall_port_cache_db_match(
                                in_port_t port,
@@ -94,12 +117,11 @@
 
 
 /**
- * hip_firewall_port_hash_key:
- * Generates the hash information that is used to index the table
- *
- * @param ptr: pointer to the hit used to make the hash
- *
- * @return hash information
+ * Generate the hash information that is used to index the table
+ *
+ * @param ptr pointer to the hit used to assemble the hash
+ *
+ * @return hash value
  */
 static unsigned long hip_firewall_port_hash_key(const void *ptr){
         char *key = (char *)(&((firewall_port_cache_hl_t 
*)ptr)->port_and_protocol);
@@ -112,11 +134,10 @@
 
 
 /**
- * hip_firewall_match_port_cache_key:
- * Compares two port_and_protocol keys
+ * Compare two keys for the hashtable
  *
- * @param ptr1: pointer to key
- * @param ptr2: pointer to key
+ * @param ptr1 pointer to the first key
+ * @param ptr2 pointer to the second key
  *
  * @return 0 if hashes identical, otherwise 1
  */
@@ -124,9 +145,13 @@
        return (hip_firewall_port_hash_key(ptr1) != 
hip_firewall_port_hash_key(ptr2));
 }
 
-
+/**
+ * Initialize port cache database
+ * 
+ */
 void firewall_port_cache_init_hldb(void){
        firewall_port_cache_db = hip_ht_init(hip_firewall_port_hash_key,
                                        hip_firewall_match_port_cache_key);
 }
 
+

=== removed file 'firewall/cache_port.c.doxyme'
--- firewall/cache_port.c.doxyme        2009-12-12 10:44:54 +0000
+++ firewall/cache_port.c.doxyme        1970-01-01 00:00:00 +0000
@@ -1,63 +0,0 @@
-/**
- * @file firewall/cache_port.c
- *
- * <LICENSE TEMLPATE LINE - LEAVE THIS LINE INTACT>
- *
- * Write description of source file here for dOxygen. Be as precise as 
possible.
- * Please also note how and by which parts of the code this file should be 
used.
- *
- * @brief Write a short summary
- *
- * @author <Put all existing author information here>
- * @author another Author another@xxxxxxxxxx
- **/
-
-
-
- ///  Single line comment for dOxygen.
-
-/**
- * my_great_function
- *
- * Write description of function here.
- * The function should follow these comments.
- * 
- * Document the use of each function variable and indicate if this
- * argument is used to return information to the calling context. Use
- * [out] for outut parameters (This is very important). Align the 
- * descriptions to improve readability.
- *
- *  @note: put important usage informations to notes. 
- *
- *  @param      firstArg     Description of first function argument.
- *  @param[out] secondArg    Description of second function argument.
- *  @param      thirdArg     Description of third function argument.
- *  @return Description of returned value.
- **/
-
-int my_great_function(int firstArg, char** secondArg, int thirdArg){
-    .....
-
-/// Now it's your turn.
-
-
-
-
-/**
- * firewall_port_cache_db_match 
- *
- *
- * @param port
- * @param proto
- * @return 
- **/
-
-
-/**
- * firewall_port_cache_init_hldb 
- *
- *
- * @param void
- * @return 
- **/
-

Other related posts:

  • » [hipl-commit] [trunk] Rev 3546: Doxygen for cache_port.c - Miika Komu