Merge pull request #79 from wriaz/master

Added doc strings for header files

twister/include/arplogic.h

@@ -1,3 +1,7 @@
+/** @file Contains ARP functionality
+ *
+ */
+
 #ifndef _ARPLOGIC_H_
 #define _ARPLOGIC_H_
 
@@ -15,9 +19,47 @@ struct ether_addr broadcastmac;
 struct arp_table * arp_table_root;
 uint32_t arp_table_size;
 
-int tw_parse_arp(struct rte_mbuf *, uint8_t);
-int tw_send_arp_reply(struct rte_mbuf *, uint8_t);
-int tw_process_arp_reply(struct rte_mbuf* pkt, uint8_t);
-int tw_add_arp_entry(uint32_t ip_to_add, struct ether_addr, uint8_t);
+/** Parses any ARP packet received
+ *
+ * @param rte_mbuf :Pointer to memory buffer holding the msg
+ *
+ * @param uint8_t : ID of port
+ *
+ * @return 0(TRUE)
+ */
+int tw_parse_arp(struct rte_mbuf * pkt, uint8_t port_id);
+
+/** Sends reply to an ARP request
+ *
+ * @param pkt : Pointer to ARP request packet
+ *
+ * @param port_id :ID of port
+ *
+ * @return 0(TRUE)
+ *
+ */
+int tw_send_arp_reply(struct rte_mbuf * pkt, uint8_t port_id);
+
+/** Process the ARP reply.
+ *
+ * @param pkt : Pointer to the ARP reply packet
+ *
+ * @param port_id :ID of port
+ *
+ * @return 0(TRUE)
+ *
+ */
+int tw_process_arp_reply(struct rte_mbuf* pkt, uint8_t port_id);
+
+/** Add a new ARP entry to the table
+ *
+ * @param ip_to_add :New IP to add to table
+ *
+ * @param mac_to_add :New MAC address to add
+ *
+ * @return 0(TRUE)
+ *
+ */
+int tw_add_arp_entry(uint32_t ip_to_add, struct ether_addr mac_to_add, uint8_t port_id);
 
 #endif

twister/include/common.h

@@ -1,3 +1,7 @@
+/** @file Contains commonly used, helpful functions.
+ *
+ */
+
 #ifndef _COMMON_H_
 #define _COMMON_H_
 
@@ -9,9 +13,47 @@
 #include <rte_byteorder.h>
 #include <tw_common.h>
 
-uint8_t tw_str_len(const char *);
-void tw_slice_array(const char *, char *, uint8_t, uint8_t);
-uint8_t tw_find_char(const char *, int *, char, uint8_t);
-int tw_power(uint8_t, uint8_t);
+/** Finds the length of a string
+ *
+ * @param str :Pointer to string
+ *
+ * @return Length of string str
+ */
+uint8_t tw_str_len(const char * str);
+
+/**
+ * @param srcStr :String to slice
+ *
+ * @param dstStr :Pointer to new string
+ *
+ * @param start :Start point of slice
+ *
+ * @param dstLength :Length of slice
+ *
+ * @return
+ */
+void tw_slice_array(const char * srcStr, char * dstStr, uint8_t start, uint8_t dstLength);
+
+/**
+ * @param str :String to search
+ *
+ * @param quoteLoc :
+ *
+ * @param c :Character to search
+ *
+ * @param instance : Number of occurrences
+ * @return
+ */
+uint8_t tw_find_char(const char * str, int * quoteLoc, char c, uint8_t instance);
+
+/** Evaluates base to the exponent
+ *
+ * @param base :Base
+ *
+ * @param exp :Exponent
+ *
+ * @return Result of calculation
+ */
+int tw_power(uint8_t base, uint8_t exp);
 
 #endif

twister/include/eth.h

@@ -1,3 +1,6 @@
+/** @file Ethernet layer functionality
+ *
+ */
 #ifndef _ETH_H_
 #define _ETH_H_
 
@@ -11,7 +14,28 @@
 
 uint8_t eth_hdr_size;
 
-int tw_eth_pkt_ctor(struct rte_mbuf*, uint8_t, uint16_t, uint32_t);
-int tw_eth_pkt_parser(struct rte_mbuf *, uint8_t);
+/** Ethernet packet constructor
+ *
+ * @param m :Pointer to packet
+ *
+ * @param port_id: ID of port
+ *
+ * @param eth_type: Type of Ethernet packet
+ *
+ * @param dst_ip: Destination IP
+ *
+ * @return 0(TRUE)
+ */
+int tw_eth_pkt_ctor(struct rte_mbuf* m, uint8_t port_id, uint16_t eth_type, uint32_t dst_ip);
+
+/** Parses any ethernet packet received
+ *
+ * @param pkt :Pointer to received Ethernet packet
+ *
+ * @param port_id: ID of port
+ *
+ * @return 0(TRUE)
+ */
+int tw_eth_pkt_parser(struct rte_mbuf * pkt, uint8_t port_id);
 
 #endif

twister/include/event_loop.h

@@ -1,3 +1,7 @@
+/** @file Provides all the functionality of the event loop
+ *
+ */
+
 #ifndef _EVENT_LOOP_H_
 #define _EVENT_LOOP_H_
 #include <rte_config.h>
@@ -31,13 +35,21 @@ enum
     TW_TIMER_HANDLE = 0x05
 };
 
+/** Struct containing info about handlers
+ *
+ * @bug Not used
+ *
+ */
 struct tw_handle_s
 {
         uint8_t handle_type;
         uint64_t last_run_time;
         struct tw_handle_s * next;
 }__attribute__((__packed__));
 
+/** Struct containing info about event loop
+ *
+ */
 struct tw_loop_s
 {
         /* User data - use this for whatever. */
@@ -57,6 +69,9 @@ struct tw_loop_s
 typedef struct tw_loop_s tw_loop_t;
 typedef struct tw_handle_s tw_handle_t;
 
+/** Struct for UDP handlers.
+ * @bug Not Used
+ */
 struct tw_udp_s
 {
         uint8_t handle_type;
@@ -69,6 +84,9 @@ struct tw_udp_s
         struct tw_udp_s * next;
 };
 
+/** Struct for rx handler.
+ *
+ */
 struct tw_rx_s
 {
         uint8_t handle_type;
@@ -80,6 +98,9 @@ struct tw_rx_s
         struct tw_rx_s * next;
 };
 
+/** Struct for tx handler
+ *
+ */
 struct tw_tx_s
 {
         uint8_t handle_type;
@@ -91,6 +112,9 @@ struct tw_tx_s
         void * tx_cb;
 };
 
+/** Struct for timer handler
+ *
+ */
 struct tw_timer_s
 {
         uint8_t handle_type;
@@ -111,7 +135,20 @@ typedef struct tw_timer_s tw_timer_t;
 
 typedef void * tw_timer_cb;
 
-int tw_loop_init(tw_loop_t *);
+/** Used to initialize the event loop
+ *
+ * @param *event_loop :Pointer to event loop struct.
+ *
+ * @return 0(TRUE)
+ */
+int tw_loop_init(tw_loop_t * event_loop);
+
+/** Used to stop the event loop
+ *
+ * @param *event_loop :Pointer to event loop struct.
+ *
+ * @return 0(TRUE)
+ */
 int tw_stop(tw_loop_t *);
 
 #endif

twister/include/initfuncs.h

@@ -1,3 +1,6 @@
+/** @file Contains all functions necessary to initialize Twister environment
+ *
+ */
 #ifndef _INITFUNCS_H_
 #define _INITFUNCS_H_
 #include <rte_ip.h>
@@ -15,6 +18,9 @@
 #include <portconf.h>
 #include <tw_api.h>
 
+/** Structure to hold application parameters such as cores and ports
+ *
+ */
 struct app_params
 {
         /* CPU cores */
@@ -56,6 +62,9 @@ struct app_params
         uint32_t pipeline_type;
 }__rte_cache_aligned;
 
+/** Structure to hold configuration of Twister such as blacklist ports.
+ *
+ */
 struct tw_conf
 {
         char * portmask;
@@ -66,12 +75,52 @@ struct tw_conf
 
 struct app_params app;
 
-int tw_smoke_init_eal_env(int , char **);
-int tw_init_eal_env(int, char **);
+/** Initializer function used for smoke test
+ *
+ * @return 0(TRUE), -1(False)
+ */
+int tw_smoke_init_eal_env(int argc, char ** argv);
+
+/** Initializes environment abstraction layer
+ *
+ * @return 0(TRUE), -1(FALSE)
+ */
+int tw_init_eal_env(int argc, char ** argv);
+
+/** Parses application specific parameters
+ *
+ * @return 0(TRUE), -1(FALSE)
+ */
 int tw_parse_twister_args(int argc, char **argv);
+
+/** Reads the parameters from conf file
+ *
+ * @param tw_conf_path :Path of the conf file
+ *
+ * @return 0(TRUE)
+ */
 int tw_parse_conf(const char * tw_conf_path);
+
+/** Calls another function which assigns IP to port
+ *
+ * @return 0(TRUE)
+ */
 int tw_init_user_given_vals(void);
-int tw_display_usage(const char *);
-int tw_parse_portmask(const char *);
+
+/** Displays an error if the current configuration is invalid
+ *
+ * @param prgname :Name of program
+ *
+ * @return 0(TRUE)
+ */
+int tw_display_usage(const char * prgname);
+
+/** Parses the hexadecimal port mask to return a decimal value
+ *
+ * @param portmask : Port mask in hexadecimal
+ *
+ * @return The port mask in decimal form
+ */
+int tw_parse_portmask(const char * portmask);
 
 #endif

twister/include/jsonparser.h

@@ -1,3 +1,6 @@
+/**@file Contains functions related to the json file.
+ *
+ */
 #ifndef _JSONPARSER_H_
 #define _JSONPARSER_H_
 
@@ -8,9 +11,21 @@
 #include "cJSON.h"
 #include <tw_common.h>
 
-char * tw_registerfile(const char *);
-int tw_get_port_conf_json_vals(const char *);
-int tw_get_lcore_queue_conf_json_vals(const char *);
-int tw_get_processing_conf_json_vals(const char *);
+/** Registers the json file and retrieves its raw data.
+ *
+ * @param filename :Name of file to register
+ *
+ * @return Raw data of file
+ */
+char * tw_registerfile(const char * filename);
+
+/** Assigns IP to port
+ *
+ * @param file_name :Name of json file
+ *
+ * @return 0(TRUE), -1(FALSE)
+ */
+int tw_get_port_conf_json_vals(const char * file_name);
+
 
 #endif