Links
- https://bugs.libre-soc.org/show_bug.cgi?id=758
- Pypowersim
- Media directory
- MP3 test directory
- Machine-readable executable Power ISA 3.0 pseudocode
Prerequisite installation
pypowersim is part of the openpower-isa repository. It is easiest installed with the 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:
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 has been created which understands IBM MSB0 ordering. Even a RADIX MMU has been implemented, 100% in python using IBM-sponsored gem5-experimental 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 support as Microwatt. PowerISA binaries are decoded by an ISA class instance. 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, 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.
Appendix - Historical notes for design decisions, and further work
As originally conceived, the goal of the project was to deliver a high-performance user space simulator of the scalar POWER ISA and our SVP64 vector extension. A high-performance C-based RISC-V simulator, Cavatools, was chosen as a base. Later on, as a measure of the needed funds and skills become clear, a change of scope was adopted. Instead, our new goal was to extend and improve our own existing reference Python simulator, with those instructions. However, as much as possible was done in C. A C based Power ISA decoder [1] (as a general-purpose library) and a Pseudo-code to C compiler [2] were written. This means that a competent team can take our work and complete a C-based Cavatools port. Also, a Test API [3] was defined, which helps to define a standard way to collect and compare the results from different implementations by abstracting away a certain level of complexity.
Relevant Milestones: