From: Andrey Miroshnikov <andrey@technepisteme.xyz>
Date: Tue, 12 Sep 2023 18:50:39 +0000 (+0000)
Subject: pypowersim_tut: Added section on test_caller tests, in progress...
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=fc67781e611ca0a2c7af49b16a6cf25bbbc63c9e;p=libreriscv.git

pypowersim_tut: Added section on test_caller tests, in progress...
---

diff --git a/docs/pypowersim_tut.mdwn b/docs/pypowersim_tut.mdwn
index 07b432eaf..6f47abe39 100644
--- a/docs/pypowersim_tut.mdwn
+++ b/docs/pypowersim_tut.mdwn
@@ -1,10 +1,46 @@
 # Pypowersim/ISACaller tutorial - In progress!
 
+* PowerPC Arch assembler lecture: <https://www.eecs.umich.edu/courses/eecs373.w04/Lectures/stever_old_lectures/lec2.pdf>
+* Hello world in PPC64 assembly: <https://github.com/matja/asm-examples/blob/master/ppc64/hello.ppc64.linux.syscall.gas.asm>
+* Hello world in PPC64LE assembly: <https://gist.github.com/sandip4n/09b50786e88968faaecdf42360c85b1b>
+
 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)*.
+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