From 7dc039e9500514d7050334a025de9c64f5a3da01 Mon Sep 17 00:00:00 2001 From: Andrey Miroshnikov Date: Sun, 10 Sep 2023 18:12:24 +0000 Subject: [PATCH] pypowersim_tut: Added temp page for documenting pypowersim tutorial --- docs/pypowersim_tut.mdwn | 92 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/pypowersim_tut.mdwn diff --git a/docs/pypowersim_tut.mdwn b/docs/pypowersim_tut.mdwn new file mode 100644 index 000000000..1b89d1d78 --- /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). + + -- 2.30.2