# Pypowersim/ISACaller tutorial - In progress!
Useful Links (Libre-SOC):
* (**Very Useful**) OpenPOWER ISA Pseudo-code:
Useful Links (External):
* PowerPC Arch assembler lecture:
* Hello world in PPC64 assembly:
* Hello world in PPC64LE assembly:
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`](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/test_caller_alu.py;hb=HEAD).
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](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/test/alu/alu_cases.py;hb=HEAD)
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](https://crypto.stackexchange.com/a/101505)).
This page will go into the details of running the simulator, not the SVP64
specifics. Please see the SVP64 Cookbook page on
[ChaCha20](https://libre-soc.org/openpower/sv/cookbook/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](https://libre-soc.org/irclog/latest.log.html#t2023-09-10T18:44:49).