documentation updates

testproject/IPL4_example.ttcn

@@ -48,7 +48,7 @@ module IPL4_example {
 	}
 
 	/* generate a flow_info using pre-defined default addresses + * incremented port */
-	function flow_gen(integer port_delta, unsignedbyte l4_prot := tsc_IP_Protocol_UDP) return flow_info {
+	private function flow_gen(integer port_delta, unsignedbyte l4_prot := tsc_IP_Protocol_UDP) return flow_info {
 		var flow_info flowi := {
 			l3_protocol := 2,
 			src_ip := "1.1.1.200",
@@ -60,7 +60,7 @@ module IPL4_example {
 		return flowi
 	}
 
-	function get_random_port_offset() return unsignedshort {
+	private function get_random_port_offset() return unsignedshort {
 		var float r := rnd();
 		return float2int(r * (65535.0 - 2000.0));
 	}
@@ -161,6 +161,7 @@ module IPL4_example {
 		return flows.flow_list[0];
 	}
 
+	/* generate + send packet for given flow through TUN */
 	function flow_send_pkt_tun1(flow_info flowi, pkt_info pkti) runs on dummy_CT {
 		var octetstring pkt := flow_gen_pkt(flowi, pkti);
 		TUN.send(tunmsg(pkt));
@@ -176,6 +177,7 @@ module IPL4_example {
 		}
 	}
 
+	/* generate + send packet for given flow through TUN2 */
 	function flow_send_pkt_tun2(flow_info flowi, pkt_info pkti) runs on dummy_CT {
 		var octetstring pkt := flow_gen_pkt(flowi, pkti);
 		TUN2.send(tunmsg(pkt));
@@ -191,6 +193,7 @@ module IPL4_example {
 		}
 	}
 
+	/* get nf_conntrack from kernel for given flow and match against template */
 	function get_nfct_and_match(flow_info flowi, template Flow t_flow) return boolean {
 		var Flow ct := f_get_conntrack(flowi);
 		var boolean ret := match(ct, t_flow);
@@ -202,6 +205,7 @@ module IPL4_example {
 		return ret;
 	}
 
+	/* get nf_conntrack from kernel for given flow and ensure there is none */
 	function get_nfct_ensure_none(flow_info flowi) return boolean {
 		var Flows cts := f_get_conntracks(flowi);
 		var boolean ret := false;
@@ -215,7 +219,6 @@ module IPL4_example {
 		return ret;
 	}
 
-
 	/* apply a certain tolerance of up to 1 second in the timeout * retrieved after the packet traversed conntrack */
 	function timeout_range(NonNegativeInteger secs) return template NonNegativeInteger {
 		return (secs-1 .. secs);
@@ -226,6 +229,7 @@ module IPL4_example {
 		tflow.meta_2.choice.indep_group.timeout_ := timeout_range(tout);
 	}
 
+	/* shared init function for all test cases */
 	function init() runs on dummy_CT {
 		if (initialized) {
 			return;
@@ -235,14 +239,7 @@ module IPL4_example {
 		initialized := true;
 	}
 
-	testcase TC_xml() runs on dummy_CT {
+	/* generate pkt_info based on arguments */
-		var charstring xml;
-		init();
-		xml := f_get_conntracks_xml()
-		log(xml)
-		log(dec_Flows(unichar2oct(xml)))
-	}
-
 	function pkti_gen(in nfct_direction direction, in octetstring payload := ''O,
 			  in NonNegativeInteger trunc_len := 0, in boolean exp_pass := true) return pkt_info {
 		var pkt_info pkti := {
@@ -254,6 +251,17 @@ module IPL4_example {
 		return pkti;
 	}
 
+	/* just verify that we can get conntrack XML and parse it */
+	testcase TC_xml() runs on dummy_CT {
+		var charstring xml;
+		init();
+		xml := f_get_conntracks_xml()
+		log(xml)
+		log(dec_Flows(unichar2oct(xml)))
+	}
+
+
+	/* test for classic netfilter UDP '3way handshake' ORIG, REPL, ORIG */
 	testcase TC_udp_3way() runs on dummy_CT {
 		var flow_info flowi := flow_gen(get_random_port_offset())
 		var Flow ct;
@@ -283,6 +291,7 @@ module IPL4_example {
 		setverdict(pass);
 	}
 
+	/* test for inverse netfilter UDP '3way handshake' ORIG, REPL, REPL */
 	testcase TC_udp_uni2() runs on dummy_CT {
 		var flow_info flowi := flow_gen(get_random_port_offset());
 		var template Flow t_flow;
@@ -314,6 +323,7 @@ module IPL4_example {
 		setverdict(pass);
 	}
 
+	/* truncated UDP header should neither pass nor create conntrack */
 	testcase TC_udp_shorthdr() runs on dummy_CT {
 		var flow_info flowi := flow_gen(get_random_port_offset());
 		var template Flow t_flow;
@@ -327,6 +337,7 @@ module IPL4_example {
 		setverdict(pass);
 	}
 
+	/* truncated UDP packet (full hdr, short data) should neither pass nor create conntrack */
 	testcase TC_udp_shortdata() runs on dummy_CT {
 		var flow_info flowi := flow_gen(get_random_port_offset());
 		var template Flow t_flow;

testproject/TunDevice_PT.cc

@@ -87,7 +87,7 @@ void TunDevice__PT_PROVIDER::logHex(const char *prompt, const OCTETSTRING& msg)
 	}
 }
 
-
+/* constructor */
 TunDevice__PT_PROVIDER::TunDevice__PT_PROVIDER(const char *par_port_name)
 	: PORT(par_port_name)
 {
@@ -96,6 +96,7 @@ TunDevice__PT_PROVIDER::TunDevice__PT_PROVIDER(const char *par_port_name)
 	debugging = false;
 }
 
+/* destructor */
 TunDevice__PT_PROVIDER::~TunDevice__PT_PROVIDER()
 {
 	close_device();
@@ -124,6 +125,7 @@ void TunDevice__PT_PROVIDER::Handle_Fd_Event_Writable(int fd)
 {
 }
 
+/* function called if FD becomes readable: pull packet from chardev */
 void TunDevice__PT_PROVIDER::Handle_Fd_Event_Readable(int fd)
 {
 	uint8_t msg[0xffff];
@@ -157,10 +159,12 @@ void TunDevice__PT_PROVIDER::user_unmap(const char *system_port)
 	close_device();
 }
 
+/* user calls 'start' on given port */
 void TunDevice__PT_PROVIDER::user_start()
 {
 }
 
+/* user calls 'stop' on given port */
 void TunDevice__PT_PROVIDER::user_stop()
 {
 }