[tb/wrpc] added comments to the new wrc_main_sim file

wrc_main_sim.c

-/*
+/* ****************************************************************************
  * This work is part of the White Rabbit project
  *
  * Copyright (C) 2017 CERN (www.cern.ch)
@@ -6,6 +6,20 @@
  * Author: Maciej Lipinski <maciej.lipinski@cern.ch>
  *
  * Released according to the GNU GPL, version 2 or any later version.
+ *
+ * ****************************************************************************
+ * Description:
+ * This file provides the main() function that replaces the main function of
+ * wrc_main.c file when WRPC is compiled for testbench. This is done by 
+ * configuring WRPC using make menuconfig:
+ * a) by using the default wrpc_sim_defconfig, i.e. "make wrpc_sim_defconfig", or
+ * b) by chosing in make menuconfig the following opton:
+ *    "Build simple software for test of WR PTP Core in simulatin"
+ *
+ * When compiled for testbench simulation, the main() function of this file is
+ * used. This file includes all the tests needed for different testbenches
+ * (so far only one...)
+ * ****************************************************************************
  */
 
 #include <stdio.h>
@@ -20,8 +34,23 @@
 
 void wrc_run_task(struct wrc_task *t);
 
+/*
+ * This is a variable that is meant to be set by testbench through memory-manipulation.
+ *
+ * To allow this, there are still some elements missing:
+ * - the test_number variable needs to be at a known address, this is already done
+ *   for other variables (for VLANs?), so the same needs to be done for this
+ * - testbench needs to be modified appropriately
+ *
+ * The idea behind is that different tests for different testbenches are compiled in 
+ * this file, and the proper test is loaded based on this variable. Each testbench
+ * sets the proper testbench number at th startup
+ */
 static int test_number = 0;
 
+/*
+ * Basic initialization required for simulation
+ */
 static void wrc_sim_initialize(void)
 {
   uint8_t mac_addr[6];
@@ -29,6 +58,7 @@ static void wrc_sim_initialize(void)
   sdb_find_devices();
   timer_init(1);
 
+  //Source MAC used by WRPC's Endpoint
   mac_addr[0] = 0xDE;
   mac_addr[1] = 0xAD;
   mac_addr[2] = 0xBE;
@@ -44,6 +74,23 @@ static void wrc_sim_initialize(void)
   spll_very_init();
 }
 /*
+ * This is a test used by:
+ * - WRPC testbench located in "testbench/wrc_core" folder of the wr-cores repository
+ *   (git://ohwr.org/hdl-core-lib/wr-cores.git)
+ *
+ * This test:
+ * - sends min-size frames of PTP EtherType (0x88f7) and Dst MAC (01:1B:19:00:00:00)
+ *   with embedded sequence number and flags providing information about the previously
+ *   received frame
+ * - checkes whether the transmitted frames are successfully received back in a proper 
+ *   sequence (it is supposed that the testbench loops back the frames)
+ * - embeds in the next frame flag and return value regarding the previously received 
+ *   frames, i.e.:
+ *   # the flags say:
+ *     0xAA: this is the first frame (no previous frames)
+ *     0xBB: previous frame was successfully received
+ *     0xE*: something was wrong with the previously received frame
+ *   # return value - it is the value returned by the reception funcation
  *
  */
 int wrpc_test_1(void)
@@ -71,7 +118,7 @@ int wrpc_test_1(void)
   for(j=0; j<80; ++j) {
     tx_payload[j] = 0xC7;//j;
   }
-  //address and EtherType
+  //MAC address and EtherType of PTP
   memcpy(tx_hdr.dstmac, "\x01\x1B\x19\x00\x00\x00", 6);
   tx_hdr.ethtype = htons(0x88f7);