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

bd16ce1e · Maciej Lipinski · Adam Wujek · 19789c08 · bd16ce1e
Commit bd16ce1e authored Feb 13, 2017 by Maciej Lipinski Committed by Adam Wujek Feb 23, 2017
Hide whitespace changes
Inline Side-by-side

Showing with 49 additions and 2 deletions

wrc_main_sim.c wrc_main_sim.c +49 -2

No files found.
--- a/wrc_main_sim.c
+++ b/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);