boards/intel_adsp_cavs15: Add --no-history argument to adsplog.py

The default behavior of the log reader is to dump the full device trace
buffer.  But that can contain output from a previous run and the state
parser in twister can get confused.  Add a "--no-history" argument that
emits only new log data, which corresponds more closely to the way a
hardware UART would work.

(Code change is just two lines, everything else is comments & docs)

Fixes zephyrproject-rtos#30979

Signed-off-by: Andy Ross <andrew.j.ross@intel.com>

boards/xtensa/intel_adsp_cavs15/doc/index.rst

@@ -109,14 +109,17 @@ Integration Testing With Twister
 ================================
 
 The ADSP hardware also has integration for testing using the twister
-tool.  The ``adsplog`` script can be used unmodified as the
+tool.  The ``adsplog`` script can be used as the
 ``--device-serial-pty`` handler, and the west flash script should take
-a path to the same key file used above.
+a path to the same key file used above.  Remember to pass the
+``--no-history`` argument to ``adsplog.py``, because by default it
+will dump the current log buffer, which may contain output from a
+previous test run.
 
 .. code-block:: console
 
     $ZEPHYR_BASE/scripts/twister --device-testing -p intel_adsp_cavs15 \
-      --device-serial-pty $ZEPHYR_BASE/boards/xtensa/intel_adsp_cavs15/tools/adsplog.py \
+      --device-serial-pty $ZEPHYR_BASE/boards/xtensa/intel_adsp_cavs15/tools/adsplog.py,--no-history \
       --west-flash $ZEPHYR_BASE/boards/xtensa/intel_adsp_cavs15/tools/flash.sh,$PATH_TO_KEYFILE.pem
 
 .. target-notes::

boards/xtensa/intel_adsp_cavs15/tools/adsplog.py

@@ -11,6 +11,13 @@
 
 # Log reader for the trace output buffer on a ADSP device.
 #
+# When run with no arguments, it will detect the device, dump the
+# contents of the trace buffer and continue to poll for more output.
+# The "--no-history" argument can be passed to suppress emission of the
+# history, and emit only new output.  This can be useful for test
+# integration where the user does not want to see any previous runs in
+# the log output.
+#
 # The trace buffer is inside a shared memory region exposed by the
 # audio PCI device as a BAR at index 4.  The hardware provides 4 128k
 # "windows" starting at 512kb in the BAR which the DSP firmware can
@@ -170,7 +177,13 @@ def trace_history():
 # polling.
 def main():
     next_slot, next_id, last_hist = trace_history()
-    sys.stdout.write(last_hist)
+
+    # We only have one command line argument, to suppress the history
+    # dump at the start (so CI runs don't see e.g. a previous device
+    # state containing logs from another test, and get confused)
+    if len(sys.argv) < 2 or sys.argv[1] != "--no-history":
+        sys.stdout.write(last_hist)
+
     while True:
         id, smsg = read_slot(next_slot, mem)