docs/pypowersim_tut.mdwn

   1 # Pypowersim/ISACaller tutorial - In progress!
   2
   3 This tutorial is intended to get started with Libre-SOC's in-house instruction
   4 simulator. The main Python class doing the work is called `ISACaller`, while
   5 the user is expected to call the wrapper file called `pypowersim`. From here
   6 onwards this simulator will be referred to as `pypowersim` *(final name subject
   7 to change)*.
   8
   9 ## Setup a Debian 10 chroot environment
  10
  11 **Skip this section if `pypowersim` is already present on your system.**
  12
  13 Setup new chroot:
  14
  15     $ cd dev-env-setup
  16     $ sudo bash
  17     # ./mk-deb-chroot isacaller
  18     # ./mk-deb-chroot isacaller
  19     # exit
  20     $ schroot -c isacaller
  21     (isacaller):$ cd dev-env-setup
  22     (isacaller):$ sudo bash
  23     (isacaller):# ./install-hdl-apt-reqs
  24     (isacaller):# ./hdl-tools-yosys
  25     (isacaller):# ./hdl-dev-repos
  26     (isacaller):# ./binutils-gdb-install
  27     (isacaller):# exit
  28
  29 *(NOTE to self: check if `hdl-dev-repos` actually necessary)*
  30
  31 From here on, `pypowersim` should be in your `$PATH` and can simply be called
  32 from your terminal (when inside the newly created chroot).
  33
  34     (isacaller):$ pypowersim --help
  35
  36 Help message (may change, so try yourself):
  37
  38     -i --binary=   raw (non-ELF) bare metal executable, loaded at 0x0
  39     -a --listing=  file containing bare-metal assembler (no macros)
  40     -g --intregs=  colon-separated file with GPR values
  41     -f --fpregs=   colon-separated file with FPR values
  42     -s --spregs=   colon-separated file with SPR values
  43     -l --load=     filename:address to load binary into memory
  44     -d --dump=     filename:address:len to binary save from memory
  45     -q --qemu=     run qemu co-simulation
  46     -p --pc=       set initial program counter
  47     -h --help      prints this message
  48     notes:
  49     load and dump may be given multiple times
  50     load and dump must be 8-byte aligned sizes
  51     loading SPRs accepts SPR names (e.g. LR, CTR, SRR0)
  52     numbers may be integer, binary (0bNNN) or hex (0xMMM) but not FP
  53     running ELF binaries: load SPRs, LR set to 0xffffffffffffffff
  54     TODO: dump registers
  55     TODO: load/dump PC, MSR, CR
  56     TODO: print exec and sub-exec counters at end
  57
  58 ## Running existing example
  59
  60 To start with, let's see how a comprehensive example works. A good demonstrator
  61 of the capabilities of SVP64 is the XChaCha20 encryption algorithm. (Difference
  62 between ChaCha20 and XChaCha20 being an
  63 [extended 192-bit nonce](https://crypto.stackexchange.com/a/101505)).
  64
  65 This page will go into the details of running the simulator, not the SVP64
  66 specifics. Please see the SVP64 Cookbook page on
  67 [ChaCha20](https://libre-soc.org/openpower/sv/cookbook/chacha20/)
  68 for more detailed information on the algorithm and SVP64 features.
  69
  70 To run the example.
  71
  72 *(NOTE: Need to cleanup example to make it run without modifications)*
  73
  74 First modify the path:
  75
  76     vim ../../media/pypowersim_wrapper/pypowersim_wrapper_common.h
  77
  78
  79     (isacaller):$ cd ~/src/openpower-isa/crypto/chacha20
  80     (isacaller):$ make
  81     (isacaller):$ ./test-chacha20
  82
  83 Or with `SILENCELOG=1` if you want less terminal output from the simulator:
  84
  85     (isacaller):$ SILENCELOG=1 ./test-chacha20
  86
  87 ## Explanation of the process
  88
  89 Konstantinos
  90 [summarising the process](https://libre-soc.org/irclog/latest.log.html#t2023-09-10T18:44:49).
  91
  92