perf - tests - comment and polish up test script core

tools/perf/tests/shell/lib/coresight.sh

 # SPDX-License-Identifier: GPL-2.0
 # Carsten Haitzler <carsten.haitzler@arm.com>, 2021
 
-TOOLS=$(dirname $0)/tools
+# This is sourced from a driver script so no need for #!/bin... etc. at the
+# top - the assumption below is that it runs as part of sourcing after the
+# test sets up some basic env vars to say what it is.
+
+# perf record options for the perf tests to use
+PERFRECMEM="-m ,128M"
+PERFRECOPT="$PERFRECMEM -e cs_etm//u"
 
 # These tests need to be run as root or coresight won't allow large buffers
 # and will not collect proper data
@@ -11,27 +17,33 @@ if test "$UID" -ne 0; then
 	exit 2
 fi
 
-PERFRECMEM="-m ,128M"
-PERFRECOPT="$PERFRECMEM -e cs_etm//u"
+TOOLS=$(dirname $0)/tools
 DIR="$TOOLS/coresight/$TEST"
 BIN="$DIR/$TEST"
+# If the test tool/binary does not exist and is executable then skip the test
 if ! test -x "$BIN"; then exit 2; fi
 DATD="."
+# If the data dir env is set then make the data dir use that instead of ./
 if test -n "$PERF_TEST_CORESIGHT_DATADIR"; then
-  DATD="$PERF_TEST_CORESIGHT_DATADIR";
+	DATD="$PERF_TEST_CORESIGHT_DATADIR";
 fi
+# If the stat dir env is set then make the data dir use that instead of ./
 STATD="."
 if test -n "$PERF_TEST_CORESIGHT_STATDIR"; then
-  STATD="$PERF_TEST_CORESIGHT_STATDIR";
+	STATD="$PERF_TEST_CORESIGHT_STATDIR";
 fi
 
+# Called if the test fails - error code 2
 err() {
 	echo "$1"
 	exit 1
 }
 
+# Check that some statistics from our perf
 check_val_min() {
+	STATF="$4"
 	if test "$2" -lt "$3"; then
+		echo ", FAILED" >> "$STATF"
 		err "Sanity check number of $1 is too low ($2 < $3)"
 	fi
 }
@@ -44,24 +56,36 @@ perf_dump_aux_verify() {
 	DUMP="$DATD/perf-tmp-aux-dump.txt"
 	perf report --stdio --dump -i "$1" | \
 		grep -o -e I_ATOM_F3 -e I_ASYNC -e I_TRACE_INFO > "$DUMP"
+# Simply count how many of these atoms we find to see that we are producing
+# a reasonable amount of data - exact checks are not sane as this is a lossy
+# process where we may lose some blocks and the compiler may produce different
+# code depending on the compiler and optimization options, so this is rough
+# just to see if we're either missing almost all the data or all of it
 	ATOM_F3_NUM=`grep I_ATOM_F3 "$DUMP" | wc -l`
 	ATOM_ASYNC_NUM=`grep I_ASYNC "$DUMP" | wc -l`
 	ATOM_TRACE_INFO_NUM=`grep I_TRACE_INFO "$DUMP" | wc -l`
 	rm -f "$DUMP"
 
+# Arguments provide minimums for a pass
 	CHECK_F3_MIN="$2"
 	CHECK_ASYNC_MIN="$3"
 	CHECK_TRACE_INFO_MIN="$4"
 
+# Write out statistics, so over time you can track results to see if there
+# is a pattern - for example we have less "noisy" results that produce more
+# consistent amounts of data each run, to see if over time any techinques to
+# minimize data loss are having an effect or not
 	STATF="$STATD/stats-$TEST-$DATV.csv"
 	if ! test -f "$STATF"; then
 		echo "ATOM F3 Count, Minimum, ATOM ASYNC Count, Minimum, TRACE INFO Count, Minium" > "$STATF"
 	fi
-	echo "$ATOM_F3_NUM, $CHECK_F3_MIN, $ATOM_ASYNC_NUM, $CHECK_ASYNC_MIN, $ATOM_TRACE_INFO_NUM, $CHECK_TRACE_INFO_MIN" >> "$STATF"
+	echo -n "$ATOM_F3_NUM, $CHECK_F3_MIN, $ATOM_ASYNC_NUM, $CHECK_ASYNC_MIN, $ATOM_TRACE_INFO_NUM, $CHECK_TRACE_INFO_MIN" >> "$STATF"
 
-	check_val_min "ATOM_F3" "$ATOM_F3_NUM" "$CHECK_F3_MIN"
-	check_val_min "ASYNC" "$ATOM_ASYNC_NUM" "$CHECK_ASYNC_MIN"
-	check_val_min "TRACE_INFO" "$ATOM_TRACE_INFO_NUM" "$CHECK_TRACE_INFO_MIN"
+# Actually check to see if we passed or failed.
+	check_val_min "ATOM_F3" "$ATOM_F3_NUM" "$CHECK_F3_MIN" "$STATF"
+	check_val_min "ASYNC" "$ATOM_ASYNC_NUM" "$CHECK_ASYNC_MIN" "$STATF"
+	check_val_min "TRACE_INFO" "$ATOM_TRACE_INFO_NUM" "$CHECK_TRACE_INFO_MIN" "$STATF"
+	echo ", Ok" >> "$STATF"
 }
 
 perf_dump_aux_tid_verify() {
@@ -70,16 +94,20 @@ perf_dump_aux_tid_verify() {
 # blocks in the perf data. This will go through all the TID's that are listed
 # as CID=0xabcdef and see that all the Thread IDs the test tool reports are
 # in the perf data AUX chunks
-	DUMP="$DATD/perf-tmp-aux-dump.txt"
+
+# The TID test tools will print a TID per stdout line that are being tested
 	TIDS=`cat "$2"`
-	FOUND_TIDS=`perf report --stdio --dump -i "$1" | grep -o "CID=0x[0-9a-z]\+" "$DUMP" | sed 's/CID=//g' | uniq | sort | uniq`
-	rm -f "$DUMP"
+# Scan the perf report to find the TIDs that are actually CID in hex and
+# build a list of the ones found
+	FOUND_TIDS=`perf report --stdio --dump -i "$1" | grep -o "CID=0x[0-9a-z]\+" | sed 's/CID=//g' | uniq | sort | uniq`
 
+# Iterate over the list of TIDs tha the test says it has and find them in the
+# TIDs found in the perf report
 	MISSING=""
-	for TIDHEX in $FOUND_TIDS; do
-		TID=`printf "%i" $TIDHEX`
+	for TID2 in $TIDS; do
 		FOUND=""
-		for TID2 in $TIDS; do
+		for TIDHEX in $FOUND_TIDS; do
+			TID=`printf "%i" $TIDHEX`
 			if test "$TID" -eq "$TID2"; then
 				FOUND="y"
 				break