--- /dev/null
+# Pypowersim/ISACaller tutorial - In progress!
+
+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 user is expected to call the wrapper file called `pypowersim`. From here
+onwards this simulator will be referred to as `pypowersim` *(final name subject
+to change)*.
+
+## 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.
+
+*(NOTE: Need to cleanup example to make it run without modifications)*
+
+First modify the path:
+
+ vim ../../media/pypowersim_wrapper/pypowersim_wrapper_common.h
+
+
+ (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).
+
+