3 * <https://bugs.libre-soc.org/show_bug.cgi?id=758>
4 * [Pypowersim](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/pypowersim.py)
5 * [Media directory](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=media;hb=HEAD)
6 * [MP3 test directory](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=media/audio/mp3;hb=HEAD)
7 * [Machine-readable executable Power ISA 3.0 pseudocode](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=openpower/isa;hb=HEAD)
9 # Prerequisite installation
11 pypowersim is part of the
12 [openpower-isa](https://git.libre-soc.org/?p=openpower-isa.git;a=summary)
13 repository. It is easiest installed with the [[HDL_workflow/devscripts]].
15 *Note: installation time without following the scripts has typically taken
16 new users 2-3 weeks. After much pain and failure, when they then follow the
17 advice given (formerly ignored), they find it takes under 1 day*.
21 These are multimedia tests intended to cover the inner loops of various
22 Audio/Video CODECs (such as MP3) and this guide uses them as examples
23 to demonstrate pypowersim's functionality. Other examples also exist:
25 * [basic scalar integer](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=src/test/basic_pypowersim;hb=HEAD)
26 * [basic scalar FP](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=src/test/basic_pypowersim_fp;hb=HEAD)
28 **Note 1:** This is a bare-metal simulator.
29 There's no GUI, UART, or console. To check that the tests ran
30 succesfully, you need to dump the memory contents and inspect the output.
32 **Note 2:** pypowersim is designed for ease-of-understanding of the Power
33 ISA and as a tool to check that the Power ISA Specification itself is
34 correct. For example, a python class
35 [SelectableInt](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/selectable_int.py;hb=HEAD)
36 has been created which understands IBM MSB0 ordering. Even
37 a RADIX MMU has been implemented, 100% in python using IBM-sponsored
38 [gem5-experimental](https://github.com/power-gem5/gem5/blob/gem5-experimental/src/arch/power/radixwalk.cc) work as a guide. This
39 *deliberate and conscious* design choice to focus on readability
40 and understanding makes pypowersim extremely slow: an Intel i9 running
41 at 4.8 ghz is only capable of 2,500 instructions per second.
43 # Pypowersim - PowerISA Simulator
45 Pypowersim is a PowerISA simulator written in Python. It includes
47 [RADIX MMU](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/radixmmu.py;hb=HEAD)
49 [Microwatt](https://github.com/antonblanchard/microwatt/blob/master/mmu.vhdl).
50 PowerISA binaries are decoded by an
51 [ISA class instance](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/caller.py;hb=HEAD).
52 ISACaller utilises compiled machine-readable Power ISA 3.0
53 pseudocode taken directly from the Power ISA Specification.
55 SVP64 binaries are also supported. Simulation is managed cycle by cycle,
56 for instruction and memory debugging.
57 Use of QEMU as a co-simulator is also supported for verifying the
58 binaries run identically.
60 To find out about input arg information, run the script with "-h/--help"
61 or no arguments to get the help message:
64 $ python3 openpower-isa/src/openpower/decoder/isa/pypowersim.py
70 The tests consist of running Pypowersim with several input arg's:
72 * ".gpr" text file for initialising the General Purpose (integer) Registers
73 * ".spr" text file for initialising the Special Purpose Registers
74 * Initialising the Program Counter
75 * Loading given binaries into specified memory locations
76 * Select which memory regions to dump to a file
77 * Select the executable to run
79 There are other options available (such as initialising the Floating Point
85 See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/audio/mp3/mp3_0.gpr;hb=HEAD>
87 This file sets the GPRs to explicit values prior to execution.
88 This allows for example a function call's parameters, according
90 [ABI calling convention](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/calling-conv;hb=HEAD),
91 to be set conveniently and quickly, but
92 more importantly without requiring execution of additional
95 In this example below the parameters point to areas of memory
96 that are loaded or dumped, containing the input and output areas
97 of the function. They match up with the other parameters to the
101 1 # void ff_mpadsp_apply_window_float(float *synth_buf, float *window,
102 2 # int *dither_state, float *samples,
104 4 1: 0x8000 # stack pointer
105 5 3: 0x600000 # param 1: float *sunth_buf buf
106 6 4: 0x700000 # param 2: float *window win
107 7 5: 0x800000 # param 3: int *dither_state &unused
108 8 6: 0x900000 # param 3: float *samples out
109 9 7: 1 # param 5: ptr_diff_t incr 1
114 See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/common.spr;hb=HEAD>
116 This file sets SPRs to explicit values prior to execution. In this
117 example Link Register LR is set to 0xffffffff which on completion
118 of the function sets PC to an invalid out-of-bounds value causing
125 **Example Execution**
127 See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/audio/mp3/mp3_0.sh;hb=HEAD>
129 The GPRs and SPRs above are loaded prior to execution, as is the
130 sample data (at appropriate addresses matching the function parameters).
131 After execution 128 bytes are dumped from address 0x900000.
136 3 pypowersim -g audio/mp3/mp3_0.gpr \
139 6 -l data/audio/mp3/mp3_0_data/buf${1}:0x600000 \
140 7 -l data/audio/mp3/mp3_0_data/win0:0x700000 \
141 8 -d ${2}:0x900000:128 \
142 9 -i audio/mp3/mp3_0_apply_window_float.bin
145 # Before running the media tests
147 During development, the available opcodes may change.
148 Make sure to update the auto-generated Python functions
149 simulating the instructions. Also the audio data needs to be downloaded.
151 * run "pywriter". This is an installed utility, so should be in your PATH.
152 It recompiles the machine-readable Power ISA pseudocode into
154 * Download audio data. Use the Makefile inside "openpower-isa/media" to
155 download the audio samples.
164 Run the Makefile in the "openpower-isa/media" directory with "tests" arg:
170 All the debug will go to standard output, so you may wish to direct it to a
171 log file (the file will be **big**!).
173 To suppress verbose debug log, uncomment "#export SILENCELOG = 1" in the
174 Makefile or export it manually.
176 # Running "mp3_x" tests individually
178 Inside "openpower-isa/media" directory run:
181 $ ./audio/mp3/mp3_0.sh 0 out0
184 The "out0" file will be created in the "media" directory. Change the name
185 if you don't want the second test to overwrite the results of the first.
189 If you run both tests through the makefile, the shell script
190 automatically compares the input "sample0" file with the
191 generated "out0" file.
193 For manual checking, you need to know where the "out" file is, and then
194 use the "cmp" program to compare byte by byte the sample and output
198 $ cmp out0 data/audio/mp3/mp3_0_data/samples0
201 As is usual for UNIX commands no output indicates the files are identical.