Pypowersim/ISACaller tutorial - In progress!

Useful Links (Libre-SOC):

Useful Links (External):

This tutorial is intended to get started with Libre-SOC's in-house instruction simulator. The main Python class doing the work is called ISACaller, while the more comprehensive wrapper file used to run binaries is called pypowersim.

--> START HERE <-- Run ISACaller unit tests first!

TODO: Document tutorial.

Since pypowersim is much more involved (as it requires PC, register setup, etc.), it is strogly encouraged to first write a basic unit test involving the ISACaller class.

Find appropriate umbrella test_caller_[FUNCTION].py class

The directory openpower-isa/src/openpower/decoder/isa/ contains a set of files for running unit tests using pytest. If adding tests for a new category, a new umbrella will need to be created.

The umbrella file has name of the form test_caller_[FUNCTION].py. For example of the ALU test caller, see test_caller_alu.py.

It's suggested to copy the contents of an existing test caller file.

Write unit tests under the src/openpower/test/[FUNCTION]/ directory

Once a test caller class exists, the actual tests reside under the src/openpower/test/[FUNCTION]/ directory. For example of the ALU tests, see alu_cases.py

Copy an existing file when writing new tests, which should gradually teach you how to use the ISACaller class.

Example of new test - system call instructions

Setup a Debian 10 chroot environment

Skip this section if pypowersim is already present on your system.

Setup new chroot:

$ cd dev-env-setup
$ sudo bash
# ./mk-deb-chroot isacaller
# ./mk-deb-chroot isacaller
# exit
$ schroot -c isacaller
(isacaller):$ cd dev-env-setup
(isacaller):$ sudo bash
(isacaller):# ./install-hdl-apt-reqs
(isacaller):# ./hdl-tools-yosys
(isacaller):# ./hdl-dev-repos
(isacaller):# ./binutils-gdb-install
(isacaller):# exit

(NOTE to self: check if hdl-dev-repos actually necessary)

From here on, pypowersim should be in your $PATH and can simply be called from your terminal (when inside the newly created chroot).

(isacaller):$ pypowersim --help

Help message (may change, so try yourself):

-i --binary=   raw (non-ELF) bare metal executable, loaded at 0x0
-a --listing=  file containing bare-metal assembler (no macros)
-g --intregs=  colon-separated file with GPR values
-f --fpregs=   colon-separated file with FPR values
-s --spregs=   colon-separated file with SPR values
-l --load=     filename:address to load binary into memory
-d --dump=     filename:address:len to binary save from memory
-q --qemu=     run qemu co-simulation
-p --pc=       set initial program counter
-h --help      prints this message
notes:
load and dump may be given multiple times
load and dump must be 8-byte aligned sizes
loading SPRs accepts SPR names (e.g. LR, CTR, SRR0)
numbers may be integer, binary (0bNNN) or hex (0xMMM) but not FP
running ELF binaries: load SPRs, LR set to 0xffffffffffffffff
TODO: dump registers
TODO: load/dump PC, MSR, CR
TODO: print exec and sub-exec counters at end

Running existing example

To start with, let's see how a comprehensive example works. A good demonstrator of the capabilities of SVP64 is the XChaCha20 encryption algorithm. (Difference between ChaCha20 and XChaCha20 being an extended 192-bit nonce).

This page will go into the details of running the simulator, not the SVP64 specifics. Please see the SVP64 Cookbook page on ChaCha20 for more detailed information on the algorithm and SVP64 features.

To run the example.

(isacaller):$ cd ~/src/openpower-isa/crypto/chacha20
(isacaller):$ make
(isacaller):$ ./test-chacha20

Or with SILENCELOG=1 if you want less terminal output from the simulator:

(isacaller):$ SILENCELOG=1 ./test-chacha20

Explanation of the process

Konstantinos summarising the process.