docs/pypowersim_tut.mdwn

   1 # Pypowersim/ISACaller tutorial - In progress!
   2
   3 Useful Links (Libre-SOC):
   4
   5 * (**Very Useful**) OpenPOWER ISA Pseudo-code:
   6 <https://libre-soc.org/openpower/isa/>
   7
   8 Useful Links (External):
   9
  10 * PowerPC Arch assembler lecture:
  11 <https://www.eecs.umich.edu/courses/eecs373.w04/Lectures/stever_old_lectures/lec2.pdf>
  12 * Hello world in PPC64 assembly:
  13 <https://github.com/matja/asm-examples/blob/master/ppc64/hello.ppc64.linux.syscall.gas.asm>
  14 * Hello world in PPC64LE assembly:
  15 <https://gist.github.com/sandip4n/09b50786e88968faaecdf42360c85b1b>
  16
  17 This tutorial is intended to get started with Libre-SOC's in-house instruction
  18 simulator. The main Python class doing the work is called `ISACaller`, while
  19 the more comprehensive wrapper file used to run binaries is called
  20 `pypowersim`.
  21
  22 ## `-->` START HERE `<--` Run `ISACaller` unit tests first!
  23
  24 TODO: Document tutorial.
  25
  26 Since `pypowersim` is much more involved (as it requires PC, register setup,
  27 etc.), it is *strogly* encouraged to first write a basic unit test involving
  28 the `ISACaller` class.
  29
  30 ### Find appropriate umbrella `test_caller_[FUNCTION].py` class
  31
  32 The directory `openpower-isa/src/openpower/decoder/isa/` contains a set of files
  33 for running unit tests using pytest. If adding tests for a new category, a new
  34 umbrella will need to be created.
  35
  36 The umbrella file has name of the form `test_caller_[FUNCTION].py`.
  37 For example of the ALU test caller, see
  38 [`test_caller_alu.py`](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/test_caller_alu.py;hb=HEAD).
  39
  40 It's suggested to copy the contents of an existing test caller file.
  41
  42 ### Write unit tests under the `src/openpower/test/[FUNCTION]/` directory
  43
  44 Once a test caller class exists, the actual tests reside under the
  45 `src/openpower/test/[FUNCTION]/` directory. For example of the ALU tests, see
  46 [alu_cases.py](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/test/alu/alu_cases.py;hb=HEAD)
  47
  48 Copy an existing file when writing new tests, which should gradually teach you
  49 how to use the `ISACaller` class.
  50
  51 ### Example of new test - system call instructions
  52
  53
  54
  55 ## Setup a Debian 10 chroot environment
  56
  57 **Skip this section if `pypowersim` is already present on your system.**
  58
  59 Setup new chroot:
  60
  61     $ cd dev-env-setup
  62     $ sudo bash
  63     # ./mk-deb-chroot isacaller
  64     # ./mk-deb-chroot isacaller
  65     # exit
  66     $ schroot -c isacaller
  67     (isacaller):$ cd dev-env-setup
  68     (isacaller):$ sudo bash
  69     (isacaller):# ./install-hdl-apt-reqs
  70     (isacaller):# ./hdl-tools-yosys
  71     (isacaller):# ./hdl-dev-repos
  72     (isacaller):# ./binutils-gdb-install
  73     (isacaller):# exit
  74
  75 *(NOTE to self: check if `hdl-dev-repos` actually necessary)*
  76
  77 From here on, `pypowersim` should be in your `$PATH` and can simply be called
  78 from your terminal (when inside the newly created chroot).
  79
  80     (isacaller):$ pypowersim --help
  81
  82 Help message (may change, so try yourself):
  83
  84     -i --binary=   raw (non-ELF) bare metal executable, loaded at 0x0
  85     -a --listing=  file containing bare-metal assembler (no macros)
  86     -g --intregs=  colon-separated file with GPR values
  87     -f --fpregs=   colon-separated file with FPR values
  88     -s --spregs=   colon-separated file with SPR values
  89     -l --load=     filename:address to load binary into memory
  90     -d --dump=     filename:address:len to binary save from memory
  91     -q --qemu=     run qemu co-simulation
  92     -p --pc=       set initial program counter
  93     -h --help      prints this message
  94     notes:
  95     load and dump may be given multiple times
  96     load and dump must be 8-byte aligned sizes
  97     loading SPRs accepts SPR names (e.g. LR, CTR, SRR0)
  98     numbers may be integer, binary (0bNNN) or hex (0xMMM) but not FP
  99     running ELF binaries: load SPRs, LR set to 0xffffffffffffffff
 100     TODO: dump registers
 101     TODO: load/dump PC, MSR, CR
 102     TODO: print exec and sub-exec counters at end
 103
 104 ## Running existing example
 105
 106 To start with, let's see how a comprehensive example works. A good demonstrator
 107 of the capabilities of SVP64 is the XChaCha20 encryption algorithm. (Difference
 108 between ChaCha20 and XChaCha20 being an
 109 [extended 192-bit nonce](https://crypto.stackexchange.com/a/101505)).
 110
 111 This page will go into the details of running the simulator, not the SVP64
 112 specifics. Please see the SVP64 Cookbook page on
 113 [ChaCha20](https://libre-soc.org/openpower/sv/cookbook/chacha20/)
 114 for more detailed information on the algorithm and SVP64 features.
 115
 116 To run the example.
 117
 118     (isacaller):$ cd ~/src/openpower-isa/crypto/chacha20
 119     (isacaller):$ make
 120     (isacaller):$ ./test-chacha20
 121
 122 Or with `SILENCELOG=1` if you want less terminal output from the simulator:
 123
 124     (isacaller):$ SILENCELOG=1 ./test-chacha20
 125
 126 ## Explanation of the process
 127
 128 Konstantinos
 129 [summarising the process](https://libre-soc.org/irclog/latest.log.html#t2023-09-10T18:44:49).
 130
 131