docs/pypowersim.mdwn

   1 # Links
   2
   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)
   8
   9 # Pypowersim Guide
  10
  11 These are multimedia tests intended to cover the inner loops of various
  12 Audio/Video CODECs (such as MP3) and this guide uses them as examples
  13 to demonstrate pypowersim's functionality.  Other examples also exist:
  14
  15 * [basic scalar integer](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=src/test/basic_pypowersim;hb=HEAD)
  16 * [basic scalar FP](https://git.libre-soc.org/?p=openpower-isa.git;a=tree;f=src/test/basic_pypowersim_fp;hb=HEAD)
  17
  18 **Note 1:** This is a bare-metal simulator.
  19 There's no GUI, UART, or console. To check that the tests ran
  20 succesfully, you need to dump the memory contents and inspect the output.
  21
  22 **Note 2:** pypowersim is designed for ease-of-understanding of the Power
  23 ISA and as a tool to check that the Power ISA Specification itself is
  24 correct. For example, a python class
  25 [SelectableInt](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/selectable_int.py;hb=HEAD)
  26 has been created which understands IBM MSB0 ordering. This
  27 *deliberate and conscious* design choice to focus on readability
  28 and understanding makes pypowersim extremely slow: an Intel i9 running
  29 at 4.8 ghz is only capable of 2,500 instructions per second.
  30
  31 # Pypowersim - PowerISA Simulator
  32
  33 Pypowersim is a PowerISA simulator written in Python. It includes
  34 the **exact** same
  35 [RADIX MMU](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/radixmmu.py;hb=HEAD)
  36 support as
  37 [Microwatt](https://github.com/antonblanchard/microwatt/blob/master/mmu.vhdl).
  38 PowerISA binaries are decoded by an
  39 [ISA class instance](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/caller.py;hb=HEAD).
  40 ISACaller utilises compiled machine-readable Power ISA 3.0
  41 pseudocode taken directly from the Power ISA Specification.
  42
  43 SVP64 binaries are also supported. Simulation is managed cycle by cycle,
  44 for instruction and memory debugging.
  45 Use of QEMU as a co-simulator is also supported for verifying the
  46 binaries run identically.
  47
  48 To find out about input arg information, run the script with "-h/--help"
  49 or no arguments to get the help message:
  50
  51 * python3 openpower-isa/src/openpower/decoder/isa/pypowersim.py
  52
  53 # Tests
  54
  55
  56 The tests consist of running Pypowersim with several input arg's:
  57
  58 * ".gpr" text file for initialising the General Purpose (integer) Registers
  59 * ".spr" text file for initialising the Special Purpose Registers
  60 * Initialising the Program Counter
  61 * Loading given binaries into specified memory locations
  62 * Select which memory regions to dump to a file
  63 * Select the executable to run
  64
  65 There are other options available (such as initialising the Floating Point
  66 Registers).
  67 for
  68
  69 **Example GPR file**:
  70
  71 See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/audio/mp3/mp3_0.gpr;hb=HEAD>
  72
  73 This file sets the GPRs to explicit values prior to execution.
  74 This allows for example a function call's parameters, according
  75 to Power ISA
  76 [ABI calling convention](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/calling-conv;hb=HEAD),
  77 to be set conveniently and quickly, but
  78 more importantly without requiring execution of additional
  79 instructions.
  80
  81 In this example below the parameters point to areas of memory
  82 that are loaded or dumped, containing the input and output areas
  83 of the function.  They match up with the other parameters to the
  84 example script
  85
  86 ```
  87    1 # void ff_mpadsp_apply_window_float(float *synth_buf, float *window,
  88    2 #                                  int *dither_state, float *samples,
  89    3 #                                  ptrdiff_t incr);
  90    4 1: 0x8000        # stack pointer
  91    5 3: 0x600000      # param 1: float *sunth_buf     buf
  92    6 4: 0x700000      # param 2: float *window        win
  93    7 5: 0x800000      # param 3: int *dither_state    &unused
  94    8 6: 0x900000      # param 3: float *samples       out
  95    9 7: 1             # param 5: ptr_diff_t incr      1
  96 ```
  97
  98 **Example SPR file**
  99
 100 See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/common.spr;hb=HEAD>
 101
 102 This file sets SPRs to explicit values prior to execution. In this
 103 example Link Register LR is set to 0xffffffff which on completion
 104 of the function sets PC to an invalid out-of-bounds value causing
 105 program termination.
 106
 107 ```
 108   1 LR: 0xffffffff
 109 ```
 110
 111 **Example Execution**
 112
 113 See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/audio/mp3/mp3_0.sh;hb=HEAD>
 114
 115 The GPRs and SPRs above are loaded prior to execution, as is the
 116 sample data (at appropriate addresses matching the function parameters).
 117 After execution 128 bytes are dumped from address 0x900000.
 118
 119 ```
 120    1 #!/bin/sh -xe
 121    2
 122    3 pypowersim -g audio/mp3/mp3_0.gpr \
 123    4         -s common.spr \
 124    5         -p 0x20000000 \
 125    6         -l data/audio/mp3/mp3_0_data/buf${1}:0x600000 \
 126    7         -l data/audio/mp3/mp3_0_data/win0:0x700000 \
 127    8         -d ${2}:0x900000:128 \
 128    9         -i audio/mp3/mp3_0_apply_window_float.bin
 129 ```
 130
 131 # Before running the tests!
 132
 133 As the SVP64 spec and Libre-SOC CPU is developing, the available opcodes
 134 will grow. Make sure to update the auto-generated Python functions
 135 simulating the instructions. Also the audio data needs to be downloaded.
 136
 137 * run "pywriter". This is an installed utility, so should be in your PATH.
 138   It recompiles the machine-readable Power ISA pseudocode into
 139   executable python.
 140 * Download audio data. Use the Makefile inside "openpower-isa/media" to
 141  download the audio samples.
 142
 143 ```
 144 $ pywriter
 145 $ make wget
 146 ```
 147
 148 # Running both tests
 149
 150 Run the Makefile in the "openpower-isa/media" directory with "tests" arg:
 151
 152 * run "make tests"
 153
 154 All the debug will go to standard output, so you may wish to direct it to a
 155 log file (the file will be **big**!).
 156
 157 To suppress verbose debug log, uncomment "#export SILENCELOG = 1" in the
 158 Makefile or export it manually.
 159
 160 # Running "mp3_x" tests individually
 161
 162 Inside "openpower-isa/media" directory run:
 163
 164 * ./audio/mp3/mp3_0.sh 0 out
 165
 166 The "out" file will be created in the "media" directory. Change the name
 167 if you don't want the second test to overwrite the results of the first.
 168
 169 # Checking results
 170
 171 If you run both tests through the makefile, the shell script
 172 automatically compares the input "sample0" file with the
 173 generated "out" file.
 174
 175 For manual checking, you need to know where the "out" file is, and then
 176 use the "cmp" program to compare byte by byte the sample and output
 177 files.
 178
 179 * cmp out0 data/audio/mp3/mp3_0_data/samples0
 180
 181 No output indicates the files are identical.