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 # Prerequisite installation
  10
  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]].
  14
  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*.
  18
  19 # Pypowersim Guide
  20
  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:
  24
  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)
  27
  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.
  31
  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.
  42
  43 # Pypowersim - PowerISA Simulator
  44
  45 Pypowersim is a PowerISA simulator written in Python. It includes
  46 the **exact** same
  47 [RADIX MMU](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/radixmmu.py;hb=HEAD)
  48 support as
  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.
  54
  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.
  59
  60 To find out about input arg information, run the script with "-h/--help"
  61 or no arguments to get the help message:
  62
  63 * python3 openpower-isa/src/openpower/decoder/isa/pypowersim.py
  64
  65 # Tests
  66
  67
  68 The tests consist of running Pypowersim with several input arg's:
  69
  70 * ".gpr" text file for initialising the General Purpose (integer) Registers
  71 * ".spr" text file for initialising the Special Purpose Registers
  72 * Initialising the Program Counter
  73 * Loading given binaries into specified memory locations
  74 * Select which memory regions to dump to a file
  75 * Select the executable to run
  76
  77 There are other options available (such as initialising the Floating Point
  78 Registers).
  79 for
  80
  81 **Example GPR file**:
  82
  83 See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/audio/mp3/mp3_0.gpr;hb=HEAD>
  84
  85 This file sets the GPRs to explicit values prior to execution.
  86 This allows for example a function call's parameters, according
  87 to Power ISA
  88 [ABI calling convention](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/calling-conv;hb=HEAD),
  89 to be set conveniently and quickly, but
  90 more importantly without requiring execution of additional
  91 instructions.
  92
  93 In this example below the parameters point to areas of memory
  94 that are loaded or dumped, containing the input and output areas
  95 of the function.  They match up with the other parameters to the
  96 example script
  97
  98 ```
  99    1 # void ff_mpadsp_apply_window_float(float *synth_buf, float *window,
 100    2 #                                  int *dither_state, float *samples,
 101    3 #                                  ptrdiff_t incr);
 102    4 1: 0x8000        # stack pointer
 103    5 3: 0x600000      # param 1: float *sunth_buf     buf
 104    6 4: 0x700000      # param 2: float *window        win
 105    7 5: 0x800000      # param 3: int *dither_state    &unused
 106    8 6: 0x900000      # param 3: float *samples       out
 107    9 7: 1             # param 5: ptr_diff_t incr      1
 108 ```
 109
 110 **Example SPR file**
 111
 112 See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/common.spr;hb=HEAD>
 113
 114 This file sets SPRs to explicit values prior to execution. In this
 115 example Link Register LR is set to 0xffffffff which on completion
 116 of the function sets PC to an invalid out-of-bounds value causing
 117 program termination.
 118
 119 ```
 120   1 LR: 0xffffffff
 121 ```
 122
 123 **Example Execution**
 124
 125 See <https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=media/audio/mp3/mp3_0.sh;hb=HEAD>
 126
 127 The GPRs and SPRs above are loaded prior to execution, as is the
 128 sample data (at appropriate addresses matching the function parameters).
 129 After execution 128 bytes are dumped from address 0x900000.
 130
 131 ```
 132    1 #!/bin/sh -xe
 133    2
 134    3 pypowersim -g audio/mp3/mp3_0.gpr \
 135    4         -s common.spr \
 136    5         -p 0x20000000 \
 137    6         -l data/audio/mp3/mp3_0_data/buf${1}:0x600000 \
 138    7         -l data/audio/mp3/mp3_0_data/win0:0x700000 \
 139    8         -d ${2}:0x900000:128 \
 140    9         -i audio/mp3/mp3_0_apply_window_float.bin
 141 ```
 142
 143 # Before running the tests!
 144
 145 As the SVP64 spec and Libre-SOC CPU is developing, the available opcodes
 146 will grow. Make sure to update the auto-generated Python functions
 147 simulating the instructions. Also the audio data needs to be downloaded.
 148
 149 * run "pywriter". This is an installed utility, so should be in your PATH.
 150   It recompiles the machine-readable Power ISA pseudocode into
 151   executable python.
 152 * Download audio data. Use the Makefile inside "openpower-isa/media" to
 153  download the audio samples.
 154
 155 ```
 156 $ pywriter
 157 $ make wget
 158 ```
 159
 160 # Running both tests
 161
 162 Run the Makefile in the "openpower-isa/media" directory with "tests" arg:
 163
 164 * run "make tests"
 165
 166 All the debug will go to standard output, so you may wish to direct it to a
 167 log file (the file will be **big**!).
 168
 169 To suppress verbose debug log, uncomment "#export SILENCELOG = 1" in the
 170 Makefile or export it manually.
 171
 172 # Running "mp3_x" tests individually
 173
 174 Inside "openpower-isa/media" directory run:
 175
 176 * ./audio/mp3/mp3_0.sh 0 out
 177
 178 The "out" file will be created in the "media" directory. Change the name
 179 if you don't want the second test to overwrite the results of the first.
 180
 181 # Checking results
 182
 183 If you run both tests through the makefile, the shell script
 184 automatically compares the input "sample0" file with the
 185 generated "out" file.
 186
 187 For manual checking, you need to know where the "out" file is, and then
 188 use the "cmp" program to compare byte by byte the sample and output
 189 files.
 190
 191 * cmp out0 data/audio/mp3/mp3_0_data/samples0
 192
 193 No output indicates the files are identical.