From bb930688a69ab188aecf47ecc87bd220efc5e61a Mon Sep 17 00:00:00 2001
From: Andrey Miroshnikov <andrey@technepisteme.xyz>
Date: Tue, 28 Jun 2022 19:33:57 +0100
Subject: [PATCH] Added documentation of the pypowersim testing

---
 docs/pypowersim.mdwn | 101 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 99 insertions(+), 2 deletions(-)

diff --git a/docs/pypowersim.mdwn b/docs/pypowersim.mdwn
index 45415eff2..f094c2c2c 100644
--- a/docs/pypowersim.mdwn
+++ b/docs/pypowersim.mdwn
@@ -1,4 +1,101 @@
+# Links
 
-# TODO
+* <https://bugs.libre-soc.org/show_bug.cgi?id=758>
+* [Pypowersim](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/pypowersim.py)
+* [Media directory](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=media;hb=HEAD)
+* [MP3 test directory](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=media/audio/mp3;hb=HEAD)
 
-<https://bugs.libre-soc.org/show_bug.cgi?id=758>
+# Pypowersim Guide
+
+These are multimedia tests intended to cover the inner loops of various
+Audio/Video CODECs (such as MP3).
+
+**Note:** There's no GUI, UART, or console. To check that the tests ran
+succesfully, you need to dump the memory contents and inspect them.
+
+
+## Pypowersim
+
+**NOTE**: This is a basic description, as the author has not studied or used
+the simulator in great detail.
+
+Pypowersim is a Python script containing useful functions for PowerISA testing.
+Assembler code written in SV is decoded by a given ISA class instance, and a
+simulation is managed cycle by cycle, for instruction and memory debugging.
+Use of QEMU as a co-simulator is also supported.
+
+To find out about input arg information, run the script with "-h/--help" or 
+no arguments to get the help message:
+
+* python3 openpower-isa/src/openpower/decoder/isa/pypowersim.py
+
+## Tests
+
+### About
+
+The tests consist of running the "pypowersim" tool with several input arg's:
+
+* ".gpr" text file for initialising the General Purpose (integer) Registers
+* ".spr" text file for initialising the Special Purpose Registers
+* Initialising the Program Counter
+* Loading given binaries into specified memory locations
+* Select which memory regions to dump to a file
+* Select the executable to run
+
+There are other options available (such as initialising the Floating Point
+Registers).
+for 
+
+### Before running the tests!
+
+**NOTE**: Is this correct?
+
+As the SVP64 spec and Libre-SOC CPU is developing, the available opcodes
+will grow. Make sure to update the auto-generated Python functions
+simulating the instructions by calling:
+
+* run "pywriter"
+
+(This is an installed utility, so should be in your PATH)
+
+### Download audio data (**only need to do this once?**)
+
+Call the Makefile inside "openpower-isa/media" to download the audio
+samples:
+
+* run "make wget"
+
+### Running both tests
+
+Run the Makefile in the "openpower-isa/media" directory with "tests" arg:
+
+* run "make tests"
+
+All the debug will go to standard output, so you may wish to direct it to a
+log file (the file will be **big**!).
+
+To suppress verbose debug log, uncomment "#export SILENCELOG = 1" in the
+Makefile.
+
+### Running "mp3_x" tests individually
+
+Inside "openpower-isa/media" directory run:
+
+* ./audio/mp3/mp3_0.sh 0 out
+
+The "out" file will be created in the "media" directory. Change the name
+if you don't want the second test to overwrite the results of the first. 
+
+### Checking results
+
+If you run both tests through the makefile, the shell script
+automatically compares the input "sample0" file with the
+generated "out" file.
+
+For manual checking, you need to know where the "out" file is, and then
+use the "cmp" program to compare byte by byte the sample and output
+files.
+
+* cmp out0 data/audio/mp3/mp3_0_data/samples0
+
+No output indicates the files are identical.
-- 
2.30.2