* [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)
-# Pypowersim Guide
+# Prerequisite installation
-These are multimedia tests intended to cover the inner loops of various
-Audio/Video CODECs (such as MP3).
+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:** There's no GUI, UART, or console. To check that the tests ran
-succesfully, you need to dump the memory contents and inspect them.
+*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
-## Pypowersim - PowerISA Simulator
+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.
-Pypowersim is a PowerISA simulator written and Python.
-PowerISA binaries are decoded by a given ISA class instance.
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
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
+# Tests
-### About
The tests consist of running Pypowersim with several input arg's:
9 -i audio/mp3/mp3_0_apply_window_float.bin
```
-### 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"
+# Before running the media tests
-(This is an installed utility, so should be in your PATH)
+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.
-### Download audio data (**only need to do this once?**)
+* 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.
-Call the Makefile inside "openpower-isa/media" to download the audio
-samples:
-
-* run "make wget"
+```
+$ pywriter
+$ make wget
+```
-### Running both tests
+# Running both tests
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**!).
To suppress verbose debug log, uncomment "#export SILENCELOG = 1" in the
-Makefile.
+Makefile or export it manually.
-### Running "mp3_x" tests individually
+# Running "mp3_x" tests individually
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
+# 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.
projects / libreriscv.git / blobdiff