cleanup for moonsniff.cpp

src/moonsniff.cpp

@@ -16,13 +16,23 @@
 #define UINT24_MAX 16777215
 #define INDEX_MASK (uint32_t) 0x00FFFFFF
 
+/*
+ * This namespace holds functions which are used by MoonSniff's Live Mode
+ *
+ * Other modes are implemented in examples/moonsniff/
+ */
 namespace moonsniff {
 
 	struct ms_timestamps {
-		uint64_t pre;
-		uint64_t post;
+		uint64_t pre; // timestamp of packet before entering DUT
+		uint64_t post; // timestamp of packet after leaving DUT
 	};
 
+	/**
+	 * Base class for all file-writers
+	 *
+	 * The writers are responsible to write pre/post timestamp pairs
+	 */
 	class Writer {
 		protected:
 			std::ofstream file;
@@ -65,6 +75,11 @@ namespace moonsniff {
 			}
 	};
 
+	/**
+	 * Base class for all file-readers
+	 *
+	 * Reads pre/post timestamp pairs from a file
+	 */
 	class Reader {
 		protected:
 			std::ifstream file;
@@ -104,7 +119,7 @@ namespace moonsniff {
 			std::streampos end;
 		public:
 			bool has_next(){
-				return end > file.tellg() ? true : false;
+				return end > file.tellg();
 			}
 
 			ms_timestamps read_from_file(){
@@ -132,23 +147,28 @@ namespace moonsniff {
 		uint64_t average_latency = 0;
 		uint32_t hits = 0;
 		uint32_t misses = 0;
-		uint32_t cold_misses = 0;
 		uint32_t inval_ts = 0;
-		uint32_t overwrites = 0;
-		uint32_t cold_overwrites = 0;
 	} stats;
 
+	/**
+	 * Enum to change the reading/writing mode
+	 */
 	enum ms_mode { ms_text, ms_binary };
 
 	std::ofstream file;
 
+	// initialize array and as many mutexes to ensure memory order
 	uint64_t hit_list[UINT24_MAX + 1] = { 0 };
 	std::mutex mtx[UINT24_MAX + 1];
 
 	Writer* writer;
 
-	bool has_hit = false;
-
+	/**
+	 * Initializes the writers for the output file. Should be called before calling other functions.
+	 *
+	 * @param fileName Name of the output file
+	 * @param mode The type of the Writer which shall be created
+	 */
 	static void init(const char* fileName, ms_mode mode){
 		if( mode == ms_binary ){
 			writer = new Binary_Writer(fileName);
@@ -157,20 +177,33 @@ namespace moonsniff {
 		}
 	}
 
-	// finish by closing the writer
+	/**
+	 * Call when finished writing operations. Closes underlying writers.
+	 */
 	static void finish(){
 		writer -> finish();
 	}
 
-	// add a new entry
+	/**
+	 * Add a pre DUT timestamp to the array.
+	 *
+	 * @param identification The identifier associated with this timestamp
+	 * @param timestamp The timestamp
+	 */
 	static void add_entry(uint32_t identification, uint64_t timestamp){
 		uint32_t index = identification & INDEX_MASK;
 		while(!mtx[index].try_lock());
 		hit_list[index] = timestamp;
 		mtx[index].unlock();
 	}
 
-	// check if an element with same identification is in the array
+	/**
+	 * Check if there exists an entry in the array for the given identifier.
+	 * Retrieves the pre DUT timestamp (if existing) and writes timestamp pair into a file.
+	 *
+	 * @param identification Identifier for which an entry is searched
+	 * @param timestamp The post timestamp
+	 */
 	static void test_for(uint32_t identification, uint64_t timestamp){
 		uint32_t index = identification & INDEX_MASK;
 		while(!mtx[index].try_lock());
@@ -185,7 +218,13 @@ namespace moonsniff {
 		}
 	}
 
-	// compute the average from the written file
+	/**
+	 * Reads the output file which contains timestamp pairs.
+	 * Computes the average latency from all pairs.
+	 *
+	 * @param fileName The name of the file generated during the sniffing phase
+	 * @param mode The mode in which the file was written (ms_text, ms_binary)
+	 */
 	static ms_stats post_process(const char* fileName, ms_mode mode){
 		Reader* reader;
 		if( mode == ms_binary ){