Added more informative comments to the mxscript files.HEADv2.4master

Signed-off-by: Dietmar Eggemann <dietmar.eggemann@arm.com>

2 files changed, 110 insertions, 86 deletions

diff --git a/bootwrapper/big-little-mp1.mxscript b/bootwrapper/big-little-mp1.mxscript
index 54106cf..c8c05ee 100644
--- a/bootwrapper/big-little-mp1.mxscript
+++ b/bootwrapper/big-little-mp1.mxscript
@@ -1,64 +1,76 @@
-// Replace the string with the absolute path of the Kingfisher model executable
-// e.g. string model = "/home/working_dir/RTSM_VE_Cortex-A15x1-A7x1";
+// SET THE DEFAULT FASTMODELS PARAMETERS
+//
+// 1. Replace the string with the absolute path of the FastModel executable
+//    e.g. string model = "/home/working_dir/RTSM_VE_Cortex-A15x1-A7x1";
 string model = "<path to the model>";
 
-// Replace the string with the absolute path of the Virutalizer+Payload software image
-// e.g. string app = "/home/working_dir/bootwrapper/img.axf"
+// 2. Replace the string with the absolute path of the Virutalizer+Payload software
+//    image e.g. string app = "/home/working_dir/bootwrapper/img.axf".
 string app   = "<path to the software image>";
 
-// Replace the string with the absolute path of the wboot.bin image created in the
-// bootwrapper/big-little directory. This image is load in flash at 0x0 and distinguishes
-// between a warm and a cold reset
+// 3. Replace the string with the absolute path of the wboot.bin image created in
+//    the bootwrapper/big-little directory. This image is load in flash at 0x0
+//    and distinguishes between a warm and a cold reset.
 string wboot = "<path to warm reset handler image>";
 
-int ctr = 0;
-
-// NOTE
-//
-// Uncomment the next 4 'string' variables and update them _only_ if the run is required
-// to generate trace output as described in docs/04-Cache-hit-rate-howto.txt. Also,
-// comment out the system() invocation on line 47 and uncomment the system() command on line 34.
-// Each 'trace' parameter is described below.
-
-// Add the path to the trace plugin
-// string trace_plugin = " --trace-plugin <path to>/GenericTrace.so";
+// 4. Invoke the FastModel with support for networking enabled.
+string networking = " -C motherboard.hostbridge.userNetworking=1 -C motherboard.hostbridge.userNetPorts=\"8080=8080\" -C motherboard.smsc_91c111.enabled=1";
 
-// Parameters for selecting the trace sources to monitor outbound cache hits
-// string trace_sources = " --parameter TRACE.GenericTrace.trace-sources=\*sw_trace_event\*,\*read_for_3_came_from_snoop\*,\*read_for_4_came_from_snoop\* ";
+// 5. Additional parameters to improve FastModels performance.
+string console = " -C motherboard.pl011_uart0.untimed_fifos=1 -C motherboard.pl011_uart1.untimed_fifos=1 -C motherboard.pl011_uart2.untimed_fifos=1 -C motherboard.pl011_uart3.untimed_fifos=1";
 
-// Add the path to the trace file where all the output will be collected
-// string trace_file = " --parameter TRACE.GenericTrace.trace-file=<path to trace file> ";
+// 6. Select which cluster (Boot Cluster mentioned in "docs/01-Usage.txt")
+//    will come out of reset on power-on: 0x1 for for primary cluster
+//    (Cortex-A15, default); 0x2 for secondary cluster (Cortex-A7).
+string dualcluster = " -C coretile.dualclustersystemconfigurationblock.CFG_ACTIVECLUSTER=0x1";
 
-// Miscellaneous parameters. The frequency at which the performance metrics of the
-// model appear in the trace source can be changed here (default is 0x100).
-// string trace_misc = " -C TRACE.GenericTrace.perf-period=0x100 -C TRACE.GenericTrace.flush=1 ";
 
-// The commented 'system' command below will launch the model and register the trace
-// sources selected in 'trace_sources' with the Generic Trace plugin selected using
-// 'trace_plugin'. Other parameters are specified in 'trace_file' & 'trace_misc'.
-// system(model + trace_plugin + trace_sources + trace_file + trace_misc + " -C coretile.cache_state_modelled=1" + " -a coretile.cluster0.\*=" + app + " -a coretile.cluster1.\*=" + app + " --verbose -S &");
+// INCLUDE OPTIONAL FASTMODELS PARAMETERS
+//
+// 1. Using the Generic Trace plugin
+//
+//    Uncomment the next 4 'string' variables and update them _only_ if the run
+//    is required to generate trace output as described in
+//    docs/04-Cache-hit-rate-howto.txt. Also, ensure that the 4 string variables
+//    are appended to the system() command invocation below. Each 'trace'
+//    parameter is described below.
+//
+//   a. Add the path to the trace plugin
+//      string trace_plugin = " --trace-plugin <path to>/GenericTrace.so";
+//
+//   b. Add parameters for selecting the trace sources to monitor outbound cache
+//      hits
+//      string trace_sources = " --parameter TRACE.GenericTrace.trace-sources=\*sw_trace_event\*,\*read_for_3_came_from_snoop\*,\*read_for_4_came_from_snoop\* ";
+//
+//   c. Add the path to the trace file where all the output will be collected
+//      string trace_file = " --parameter TRACE.GenericTrace.trace-file=<path to trace file> ";
+//
+//   d. Add miscellaneous parameters. The frequency at which the performance
+//      metrics of the model appear in the trace source can be changed here
+//      (default is 0x100).
+//      string trace_misc = " -C TRACE.GenericTrace.perf-period=0x100 -C TRACE.GenericTrace.flush=1 ";
+//
+// 2. Using MMC emulation
+//
+//    Uncomment the 'mmcimage' string variable _only_ if a run is needed using
+//    an optional rootfs MMC image built using the instructions in
+//    docs/06-Optional-rootfs-build.txt. Also ensure that the 'mmcimage' string
+//    variable is appended to the system() command invocation below.
+//    string mmcimage  = " -C motherboard.mmc.p_mmc_file=<path to mmc.img>";
 
-string networking = " -C motherboard.hostbridge.userNetworking=1 -C motherboard.hostbridge.userNetPorts=\"8080=8080\" -C motherboard.smsc_91c111.enabled=1";
-string console = " -C motherboard.pl011_uart0.untimed_fifos=1 -C motherboard.pl011_uart1.untimed_fifos=1 -C motherboard.pl011_uart2.untimed_fifos=1 -C motherboard.pl011_uart3.untimed_fifos=1";
-// Select which cluster will come out of reset on power-on: 0x1 for for primary cluster (Cortex-A15, default); 0x2 for secondary cluster (Cortex-A7).
-string dualcluster = " -C coretile.dualclustersystemconfigurationblock.CFG_ACTIVECLUSTER=0x1";
 
-// NOTE
+// START FASTMODEL EXECUTION & SET BREAKPOINTS
 //
-// _Only_ if a run is needed using an optional rootfs MMC image built using the instructions in
-// docs/06-Optional-rootfs-build.txt, then comment out the system() invocation
-// below (on line 47) and uncomment the following lines taking care to update
-// the paths accordingly.
-// string mmcimage  = "<path to mmc.img>";
-// system(model + " -C motherboard.mmc.p_mmc_file=" + mmcimage + trace_plugin + trace_sources + trace_file + trace_misc + " -C coretile.cache_state_modelled=1" + " -a coretile.cluster0.\*=" + app + " -a coretile.cluster1.\*=" + app + " --verbose -S &");
-
-// Invoke the model. It then listens for connection requests from the model debugger
-// Vanilla invocation of the model.
+// Invoke the model using the system(0 command below. It then listens for
+// connection requests from the model debugger Vanilla invocation of the
+// model. Append the string variables for optional parameters to the
+// system() command.
 system(model + " -C motherboard.flashloader0.fname=" + wboot + " -C coretile.cache_state_modelled=1" + " -a coretile.cluster0.\*=" + app + " -a coretile.cluster1.\*=" + app + networking + console + dualcluster +" --verbose -S &");
 
 // Wait for the model to load before connecting to it. There will be times when we
 // try connecting before the model has loded resulting in a "Connection refused"
 // error. Increasing 'ctr' or retrying should solve the problem.
+int ctr = 0;
 while(ctr < 400000000)
 {
 	ctr++;
diff --git a/bootwrapper/big-little-mp4.mxscript b/bootwrapper/big-little-mp4.mxscript
index 67ebec3..3b2615e 100644
--- a/bootwrapper/big-little-mp4.mxscript
+++ b/bootwrapper/big-little-mp4.mxscript
@@ -1,64 +1,76 @@
-// Replace the string with the absolute path of the Kingfisher model executable
-// e.g. string model = "/home/working_dir/RTSM_VE_Cortex-A15x4-A7x4";
+// SET THE DEFAULT FASTMODELS PARAMETERS
+//
+// 1. Replace the string with the absolute path of the FastModel executable
+//    e.g. string model = "/home/working_dir/RTSM_VE_Cortex-A15x4-A7x4";
 string model = "<path to the model>";
 
-// Replace the string with the absolute path of the Virutalizer+Payload software image
-// e.g. string app = "/home/working_dir/bootwrapper/img.axf";
+// 2. Replace the string with the absolute path of the Virutalizer+Payload software
+//    image e.g. string app = "/home/working_dir/bootwrapper/img.axf".
 string app   = "<path to the software image>";
 
-// Replace the string with the absolute path of the wboot.bin image created in the
-// bootwrapper/big-little directory. This image is load in flash at 0x0 and distinguishes
-// between a warm and a cold reset
+// 3. Replace the string with the absolute path of the wboot.bin image created in
+//    the bootwrapper/big-little directory. This image is load in flash at 0x0
+//    and distinguishes between a warm and a cold reset.
 string wboot = "<path to warm reset handler image>";
 
-int ctr = 0;
-
-// NOTE
-//
-// Uncomment the next 4 'string' variables and update them _only_ if the run is required
-// to generate trace output as described in docs/04-Cache-hit-rate-howto.txt. Also,
-// comment out the system() invocation on line 47 and uncomment the system() command on line 34.
-// Each 'trace' parameter is described below.
-
-// Add the path to the trace plugin
-// string trace_plugin = " --trace-plugin <path to>/GenericTrace.so";
+// 4. Invoke the FastModel with support for networking enabled.
+string networking = " -C motherboard.hostbridge.userNetworking=1 -C motherboard.hostbridge.userNetPorts=\"8080=8080\" -C motherboard.smsc_91c111.enabled=1";
 
-// Parameters for selecting the trace sources to monitor outbound cache hits
-// string trace_sources = " --parameter TRACE.GenericTrace.trace-sources=\*sw_trace_event\*,\*read_for_3_came_from_snoop\*,\*read_for_4_came_from_snoop\* ";
+// 5. Additional parameters to improve FastModels performance.
+string console = " -C motherboard.pl011_uart0.untimed_fifos=1 -C motherboard.pl011_uart1.untimed_fifos=1 -C motherboard.pl011_uart2.untimed_fifos=1 -C motherboard.pl011_uart3.untimed_fifos=1";
 
-// Add the path to the trace file where all the output will be collected
-// string trace_file = " --parameter TRACE.GenericTrace.trace-file=<path to trace file> ";
+// 6. Select which cluster (Boot Cluster mentioned in "docs/01-Usage.txt")
+//    will come out of reset on power-on: 0x1 for for primary cluster
+//    (Cortex-A15, default); 0x2 for secondary cluster (Cortex-A7).
+string dualcluster = " -C coretile.dualclustersystemconfigurationblock.CFG_ACTIVECLUSTER=0x1";
 
-// Miscellaneous parameters. The frequency at which the performance metrics of the
-// model appear in the trace source can be changed here (default is 0x100).
-// string trace_misc = " -C TRACE.GenericTrace.perf-period=0x100 -C TRACE.GenericTrace.flush=1 ";
 
-// The commented 'system' command below will launch the model and register the trace
-// sources selected in 'trace_sources' with the Generic Trace plugin selected using
-// 'trace_plugin'. Other parameters are specified in 'trace_file' & 'trace_misc'.
-// system(model + trace_plugin + trace_sources + trace_file + trace_misc + " -C coretile.cache_state_modelled=1" + " -a coretile.cluster0.\*=" + app + " -a coretile.cluster1.\*=" + app + " --verbose -S &");
+// INCLUDE OPTIONAL FASTMODELS PARAMETERS
+//
+// 1. Using the Generic Trace plugin
+//
+//    Uncomment the next 4 'string' variables and update them _only_ if the run
+//    is required to generate trace output as described in
+//    docs/04-Cache-hit-rate-howto.txt. Also, ensure that the 4 string variables
+//    are appended to the system() command invocation below. Each 'trace'
+//    parameter is described below.
+//
+//   a. Add the path to the trace plugin
+//      string trace_plugin = " --trace-plugin <path to>/GenericTrace.so";
+//
+//   b. Add parameters for selecting the trace sources to monitor outbound cache
+//      hits
+//      string trace_sources = " --parameter TRACE.GenericTrace.trace-sources=\*sw_trace_event\*,\*read_for_3_came_from_snoop\*,\*read_for_4_came_from_snoop\* ";
+//
+//   c. Add the path to the trace file where all the output will be collected
+//      string trace_file = " --parameter TRACE.GenericTrace.trace-file=<path to trace file> ";
+//
+//   d. Add miscellaneous parameters. The frequency at which the performance
+//      metrics of the model appear in the trace source can be changed here
+//      (default is 0x100).
+//      string trace_misc = " -C TRACE.GenericTrace.perf-period=0x100 -C TRACE.GenericTrace.flush=1 ";
+//
+// 2. Using MMC emulation
+//
+//    Uncomment the 'mmcimage' string variable _only_ if a run is needed using
+//    an optional rootfs MMC image built using the instructions in
+//    docs/06-Optional-rootfs-build.txt. Also ensure that the 'mmcimage' string
+//    variable is appended to the system() command invocation below.
+//    string mmcimage  = " -C motherboard.mmc.p_mmc_file=<path to mmc.img>";
 
-string networking = " -C motherboard.hostbridge.userNetworking=1 -C motherboard.hostbridge.userNetPorts=\"8080=8080\" -C motherboard.smsc_91c111.enabled=1";
-string console = " -C motherboard.pl011_uart0.untimed_fifos=1 -C motherboard.pl011_uart1.untimed_fifos=1 -C motherboard.pl011_uart2.untimed_fifos=1 -C motherboard.pl011_uart3.untimed_fifos=1";
-// Select which cluster will come out of reset on power-on: 0x1 for for primary cluster (Cortex-A15, default); 0x2 for secondary cluster (Cortex-A7).
-string dualcluster = " -C coretile.dualclustersystemconfigurationblock.CFG_ACTIVECLUSTER=0x1";
 
-// NOTE
+// START FASTMODEL EXECUTION & SET BREAKPOINTS
 //
-// _Only_ if a run is needed using an optional rootfs MMC image built using the instructions in
-// docs/06-Optional-rootfs-build.txt, then comment out the system() invocation
-// below (on line 47) and uncomment the following lines taking care to update
-// the paths accordingly.
-// string mmcimage  = "<path to mmc.img>";
-// system(model + " -C motherboard.mmc.p_mmc_file=" + mmcimage + trace_plugin + trace_sources + trace_file + trace_misc + " -C coretile.cache_state_modelled=1" + " -a coretile.cluster0.\*=" + app + " -a coretile.cluster1.\*=" + app + " --verbose -S &");
-
-// Invoke the model. It then listens for connection requests from the model debugger
-// Vanilla invocation of the model.
+// Invoke the model using the system(0 command below. It then listens for
+// connection requests from the model debugger Vanilla invocation of the
+// model. Append the string variables for optional parameters to the
+// system() command.
 system(model + " -C motherboard.flashloader0.fname=" + wboot + " -C coretile.cache_state_modelled=1" + " -a coretile.cluster0.\*=" + app + " -a coretile.cluster1.\*=" + app + networking + console + dualcluster +" --verbose -S &");
 
 // Wait for the model to load before connecting to it. There will be times when we
 // try connecting before the model has loded resulting in a "Connection refused"
 // error. Increasing 'ctr' or retrying should solve the problem.
+int ctr = 0;
 while(ctr < 400000000)
 {
 	ctr++;