tools/README.md: topology clean-up

We have multiple scripts parsing topologies and it's impossible to guess
the differences. Try to clarify the current status in tools/README.md

Signed-off-by: Marc Herbert <marc.herbert@intel.com>

tools/README.md

@@ -34,14 +34,36 @@
 * sof-process-state.sh
 <br> Shows the current state of a given process
 
+
+Topologies
+----------
+
+Topologies provide important information for testing.
+
 * sof-tplgreader.py
-<br> tplgtool.py wrapper, it reads info from tplgtool.py to analyze topologies.
+<br> Front-end for the (old) tplgtool.py parsing library. Prints a list of PCMs found in a
+     topology file. Provides advanced PCM filtering useful for testing.  Warning: the tool
+     confuses pipelines and PCMs and wrongly calls PCMs "pipelines" everywhere; but it
+     really is about PCMs. Unlike other scripts, prints duplex PCMs on two separate lines:
+     playback and capture.
 
 * tplgtool2.py
-<br> Dumps info from tplg binary file.
-     SOF CI uses this to generate a topology graph.
+<br> New, higher-level, "construct"-based, topology parsing library. Can also be invoked
+     standalone to prints a list of PCMs and generates a graph with more information than
+     the graph generated by the old tplgtoo.py.  As of May 2024, the topology graph
+     displayed in SOF test results has been generated by this.
 
 * tplgtool.py
-<br> Dumps info from tplg binary file. sof-tplgreader.py still use this but new features
-     will go to tplgtool2.py. When all functions are migrated to tplgtool2.py
-     it will be deprecated.
+<br> Old toplogy parsing library. Still used by sof-tplgreader.py but new features
+     will go to tplgtool2.py. When all functions are migrated to tplgtool2.py it will be
+     deprecated. Can also be invoked standalone to print a list of PCMs and to generate a
+     graph (with less information than tplgtool2.py).
+
+* common.py
+<br> PCM formatting routines to bridge the gap from Python to shell scripts.
+
+* tplgfw-sanity-check.py
+<br> Matches UUID in topology and FW, then finds out whether all module in topoloy
+     can be supported by this FW. Depends on tplgtool2.py for parsing. Implements a
+     basic firmware file parser itself.
+