+# 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)
+* [Machine-readable executable Power ISA 3.0 pseudocode](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=openpower/isa;hb=HEAD)
-<https://bugs.libre-soc.org/show_bug.cgi?id=758>
+# 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
+Audio/Video CODECs (such as MP3) and this guide uses them as examples
+to demonstrate pypowersim's functionality. Other examples also exist:
+
+* [basic scalar integer](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=src/test/basic_pypowersim;hb=HEAD)
+* [basic scalar FP](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=src/test/basic_pypowersim_fp;hb=HEAD)
+
+**Note 1:** This is a bare-metal simulator.
+There's no GUI, UART, or console. To check that the tests ran
+succesfully, you need to dump the memory contents and inspect the output.
+
+**Note 2:** pypowersim is designed for ease-of-understanding of the Power
+ISA and as a tool to check that the Power ISA Specification itself is
+correct. For example, a python class
+[SelectableInt](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/selectable_int.py;hb=HEAD)
+has been created which understands IBM MSB0 ordering. Even
+a RADIX MMU has been implemented, 100% in python using IBM-sponsored
+[gem5-experimental](https://github.com/power-gem5/gem5/blob/gem5-experimental/src/arch/power/radixwalk.cc) work as a guide. This
+*deliberate and conscious* design choice to focus on readability
+and understanding makes pypowersim extremely slow: an Intel i9 running
+at 4.8 ghz is only capable of 2,500 instructions per second.
+
+# Pypowersim - PowerISA Simulator
+
+Pypowersim is a PowerISA simulator written in Python. It includes
+the **exact** same
+[RADIX MMU](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/radixmmu.py;hb=HEAD)
+support as
+[Microwatt](https://github.com/antonblanchard/microwatt/blob/master/mmu.vhdl).
+PowerISA binaries are decoded by an
+[ISA class instance](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/caller.py;hb=HEAD).
+ISACaller utilises compiled machine-readable Power ISA 3.0
+pseudocode taken directly from the Power ISA Specification.
+
+SVP64 binaries are also supported. Simulation is managed cycle by cycle,
+for instruction and memory debugging.
+Use of QEMU as a co-simulator is also supported for verifying the
+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
+```
+
+# Tests
+
+
+The tests consist of running Pypowersim 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
+
+**Example GPR file**:
+
+See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/audio/mp3/mp3_0.gpr;hb=HEAD>
+
+This file sets the GPRs to explicit values prior to execution.
+This allows for example a function call's parameters, according
+to Power ISA
+[ABI calling convention](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/calling-conv;hb=HEAD),
+to be set conveniently and quickly, but
+more importantly without requiring execution of additional
+instructions.
+
+In this example below the parameters point to areas of memory
+that are loaded or dumped, containing the input and output areas
+of the function. They match up with the other parameters to the
+example script
+
+```
+ 1 # void ff_mpadsp_apply_window_float(float *synth_buf, float *window,
+ 2 # int *dither_state, float *samples,
+ 3 # ptrdiff_t incr);
+ 4 1: 0x8000 # stack pointer
+ 5 3: 0x600000 # param 1: float *sunth_buf buf
+ 6 4: 0x700000 # param 2: float *window win
+ 7 5: 0x800000 # param 3: int *dither_state &unused
+ 8 6: 0x900000 # param 3: float *samples out
+ 9 7: 1 # param 5: ptr_diff_t incr 1
+```
+
+**Example SPR file**
+
+See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/common.spr;hb=HEAD>
+
+This file sets SPRs to explicit values prior to execution. In this
+example Link Register LR is set to 0xffffffff which on completion
+of the function sets PC to an invalid out-of-bounds value causing
+program termination.
+
+```
+ 1 LR: 0xffffffff
+```
+
+**Example Execution**
+
+See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/audio/mp3/mp3_0.sh;hb=HEAD>
+
+The GPRs and SPRs above are loaded prior to execution, as is the
+sample data (at appropriate addresses matching the function parameters).
+After execution 128 bytes are dumped from address 0x900000.
+
+```
+ 1 #!/bin/sh -xe
+ 2
+ 3 pypowersim -g audio/mp3/mp3_0.gpr \
+ 4 -s common.spr \
+ 5 -p 0x20000000 \
+ 6 -l data/audio/mp3/mp3_0_data/buf${1}:0x600000 \
+ 7 -l data/audio/mp3/mp3_0_data/win0:0x700000 \
+ 8 -d ${2}:0x900000:128 \
+ 9 -i audio/mp3/mp3_0_apply_window_float.bin
+```
+
+# Before running the media tests
+
+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.
+ It recompiles the machine-readable Power ISA pseudocode into
+ executable python.
+* Download audio data. Use the Makefile inside "openpower-isa/media" to
+ download the audio samples.
+
+```
+$ pywriter
+$ make wget
+```
+
+# Running both tests
+
+Run the Makefile in the "openpower-isa/media" directory with "tests" arg:
+
+```
+$ 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 or export it manually.
+
+# Running "mp3_x" tests individually
+
+Inside "openpower-isa/media" directory run:
+
+```
+$ ./audio/mp3/mp3_0.sh 0 out0
+```
+
+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 "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
+```
+
+As is usual for UNIX commands no output indicates the files are identical.
projects / libreriscv.git / blobdiff