ghostmansd: update status

[libreriscv.git] / docs / pypowersim.mdwn

diff --git a/docs/pypowersim.mdwn b/docs/pypowersim.mdwn
index b6ae07ab77f5a4d49dc593e3d95efa09c8eac222..33d0c5a2af22b67c950c97a1299763f3dae246b3 100644 (file)
--- a/docs/pypowersim.mdwn
+++ b/docs/pypowersim.mdwn
@@ -6,6 +6,16 @@
 * [MP3 test directory](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=media/audio/mp3;hb=HEAD)
 * [Machine-readable executable Power ISA 3.0 pseudocode](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=openpower/isa;hb=HEAD)
 
+# Prerequisite installation
+
+pypowersim is part of the
+[openpower-isa](https://git.libre-soc.org/?p=openpower-isa.git;a=summary)
+repository.  It is easiest installed with the [[HDL_workflow/devscripts]].
+
+*Note: installation time without following the scripts has typically taken
+new users 2-3 weeks. After much pain and failure, when they then follow the
+advice given (formerly ignored), they find it takes under 1 day*.
+
 # Pypowersim Guide
 
 These are multimedia tests intended to cover the inner loops of various
@@ -50,7 +60,9 @@ binaries run identically.
 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
+```
+$ python3 openpower-isa/src/openpower/decoder/isa/pypowersim.py
+```
 
 # Tests
 
@@ -130,10 +142,10 @@ After execution 128 bytes are dumped from address 0x900000.
    9         -i audio/mp3/mp3_0_apply_window_float.bin
 ```
 
-# Before running the tests!
+# Before running the media tests
 
-As the SVP64 spec and Libre-SOC CPU is developing, the available opcodes
-will grow. Make sure to update the auto-generated Python functions
+During development, the available opcodes may change.
+Make sure to update the auto-generated Python functions
 simulating the instructions. Also the audio data needs to be downloaded.
 
 * run "pywriter". This is an installed utility, so should be in your PATH.
@@ -151,7 +163,9 @@ $ make wget
 
 Run the Makefile in the "openpower-isa/media" directory with "tests" arg:
 
-* run "make tests"
+```
+$ 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**!).
@@ -163,21 +177,25 @@ Makefile or export it manually.
 
 Inside "openpower-isa/media" directory run:
 
-* ./audio/mp3/mp3_0.sh 0 out
+```
+$ ./audio/mp3/mp3_0.sh 0 out0
+```
 
-The "out" file will be created in the "media" directory. Change the name
+The "out0" 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.
+generated "out0" 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
+```
+$ cmp out0 data/audio/mp3/mp3_0_data/samples0
+```
 
-No output indicates the files are identical.
+As is usual for UNIX commands no output indicates the files are identical.