pypowersim_tut: Added temp page for documenting pypowersim tutorial

diff --git a/docs/pypowersim_tut.mdwn b/docs/pypowersim_tut.mdwn
new file mode 100644 (file)
index 0000000..1b89d1d
--- /dev/null
+++ b/docs/pypowersim_tut.mdwn
@@ -0,0 +1,92 @@
+# 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).
+
+