Updated README files

Circuit/README.md

@@ -1,9 +1,44 @@
 # Circuit
 
-Collection of logisim-evolution files that simulate various varieties of a Subleq-OISC.
-Important ones are:
+A collection of [logisim-evolution](https://github.com/logisim-evolution/logisim-evolution) project files that simulate various variants of a Subleq-OISC. Additionally, this folder contains a few test programs as .hex files.
 
+## Important Circuits
+The most importent circuits provided in this directory are:
 - slqisc.circ: A basic version without input
 - slqisc_in.circ: An upgraded version that supports input
 - slqisc_flash: A version with a separate ROM block which initialised the RAM at execution start
 - slqisc_flash_de0: A version of slqisc_flash that is suitable to be flashed on the Terasic DE0 and DE10 boards
+
+## Circuit and logic
+
+A brief explanation of the basic circuit `slqisc.circ`.
+
+### Circuit
+
+The circuit consists of a register bank (SubLoc, MinLoc, …, Min), which is used to store data for each phase of the subleq instruction. It is coordinated through a decoder by a simple counter (CTR3), which always loops after 7. A multiplexer, which is also connected to the counter, is used to determine which data source should be used as input for the RAM. There is also a register for the program counter (PC) and an adder to add the CTR3 to the PC in order to read each address sequentially. To the left, there is also a comparator, a small multiplexer, and an adder that always adds three to update the PC if there is no branch to another address.
+
+To the right, there is a ROM block that is used as a lookup table to translate numbers into letters for the small display. Each display has a register attached to store the currently displayed value. Furthermore, there is a counter and a decoder to cycle through the individual segments of the display. The comparator between the register bank and the ROM checks whether the address to be written to is ffff, in which case the value of SUB is used as the index for the lookup table to write a letter. The actual subtraction of the subleq command happens below the comparator.
+
+### Instruction
+
+Subleq is an instruction with three parameters and behaves as follows:
+For `subleq A B C`: `Mem[B] = Mem[B] - Mem[A]; if (Mem[B] <= 0) goto C`.
+It is possible to implement every other conventional instruction using only a few subleq instructions.
+
+Because the SUBLEQ computer is based on a single instruction, there is no need to store the instruction type. Therefore, each instruction consists only of three addresses.
+
+### Instruction cycle
+
+An instruction cycle contains the following seven steps.
+
+First, the value at the current program counter is loaded into the SubLoc (Subtrahend Location) register. CTR3 gets incremented and added to the PC. Now, the next value is copied into the MinLoc (Minuend Location) register, likewise with the Adr. Now, all three arguments (A, B, C) are loaded into their corresponding registers. The comparator after the MinLoc register checks the value of the MinLoc (i.e., argument B) against the fixed address `ffff` which would be interpreted as a write to the output screen. The first three steps of the cycle are now completed.
+
+After that, the value at the address, stored inside the SubLoc register, is loaded into the SubLoc register, likewise the value of the MinLoc register. The adder has now already performed the calculation, and the corresponding value can be written back into the RAM during the next step.
+
+As part of the seventh step, a comparator determines if the value is less than or equal to zero. After which the PC either gets set to the address stored inside the Adr register or is incremented by three.
+
+A full SUBLEQ cycle is now completed.
+
+## Simulation
+
+To simulate a programs `.hex` (which can be build using an [assembler](../Subleq/README.md#assembler)) load the project file into logisim evolution and right-click onto the RAM Block, to load the program (.hex) into memory. After that check if the option Auto-Tick-Enabled and Auto-Propagate under the simulate menu (top) are checked. To start the simulation go to the tab Simulate (left) and press the corresponding button.

README.md

@@ -1,14 +1,22 @@
 # SLQISC
-Subleq Assembler, Computer Circuit and other tools for teaching
 
-## Assembler
-
-Written in Haskell as a [Cabal project](https://www.haskell.org/cabal/)
+A collection of tools and implementations around the SUBLEQ (Subtract and Branch if Less than or Equal to Zero) one-instruction set computer. The project is designed for learning and teaching purposes.
 
 ## Circuit
 
-Designed in [Logisim Evolution](https://github.com/logisim-evolution/logisim-evolution)
+Multiple variants of a circuit modeling a functional SUBLEQ one instruction CPU using [Logisim Evolution](https://github.com/logisim-evolution/logisim-evolution) can be found in [/Circuit](/Circuit/).
+
+For further information, read the corresponding [README](/Circuit/README.md).
+
+## Assembler
+
+A [Haskell Cabal](https://www.haskell.org/cabal/) [project](/Subleq/) implementing an assembler and simulator to compile programs into Subleq instructions, which can then be executed on a SUBLEQ CPU.
+The simulator also provides a debug environment to simplify the development of demonstration programs for the OISC.
+
+For further information, read the corresponding [README](/Subleq/README.md).
 
 ## FPGA
 
-Written in Verilog using [Quartus Prime](https://www.intel.de/content/www/de/de/products/details/fpga/development-tools/quartus-prime.html) for the [Terasic DE10-Lite](https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&No=1021) evaluation board.
+The files located in the [/FPGA](/FPGA/) directory are generated from the Logisim Evolution circuit. The FPGA design is implemented in Verilog.
+
+These generated files represent a hardware realization of the SUBLEQ CPU and can be used for synthesis and deployment on supported FPGA platforms. In particular, the circuit can be flashed onto a [Terasic DE10-Lite](https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&No=1021) evaluation board using the [Quartus Prime](https://www.intel.de/content/www/de/de/products/details/fpga/development-tools/quartus-prime.html) software, allowing subleq programs to be executed on a physical system rather than only in simulation.

Subleq/README.md

@@ -1,8 +1,14 @@
-# SubleqCompiler
+# Subleq Compiler
 
-Basic Cabal project. Can be built with `cabal build` and ran with `cabal run assembler -- <filename.asm>`. An optional `-v` parameter allows for generation of debug logs, a CFA and intermediate compilation steps.
+This directory contains an assembler and a simulator designed to compile and test assembly code for OISC using the Subleq instruction. Additionally, it includes a collection of example programs for the assembler. The assembler and simulator are written in haskell as a [Cabal project](https://www.haskell.org/cabal/).
 
-## Befehle
+## Assembler
+
+Basic Cabal project. Can be built with `cabal build` and ran with `cabal run assembler -- <filename.asm|filename.cmm>`. An optional `-v` parameter allows for generation of debug logs, a CFA and intermediate compilation steps.
+
+The assembler takes either `.cmm` or `.asm` source and generates a `.hex` file, which can be used as input for the Logisim Evolution circuit simulations (see [../Circuit](../Circuit/)) and a `.mif` file, which is used to initialize the ROM/RAM of the FPGA in Verilog.
+
+### Befehle
 
 - „SLQ a b c“ ist das einfache SUBLEQ a b c, nur in weniger zu tippen
 - „NOP“ tut nichts
@@ -31,10 +37,12 @@ Basic Cabal project. Can be built with `cabal build` and ran with `cabal run ass
 - „STR a“ speichert den String a charweise als Wert an mehreren hintereinanderliegenden Adressen
 - „CALL a“ springt an Adresse a und speichert die Rücksprungadresse auf dem Stack (effektiv: PUSH <nextLoc>, JMP a)
 - „RET“ liest den obersten Wert vom Stack und springt an diese Adresse (effektiv, POP x, JMP x)
+- „TRP“ hält das Programm an bzw. loopt unendlich die TRP Instruktion
+- „BRK“ setzt einen Breakpoint, der vom Simulator (im debug modus) erkannt wird
 
 Der Assembler ist Case-Sensitive – Befehle sind immer in CAPS und Labels sind immer klein.
 
-## Argumente
+### Argument
 
 Argumente für die Befehle sind Zahlen (für Adressen) oder Labels. Es gibt einige Spezialwerte:
 
@@ -45,8 +53,21 @@ Argumente für die Befehle sind Zahlen (für Adressen) oder Labels. Es gibt eini
 - $O ist die Speicherstelle an die Outputs geschrieben werden können
 - $SP ist der Stackpointer
 
-## Sektionen
+Labels ersetzten in der Assemblerprogrammierung Adressen durch Namen, die während dem Compilen zu richtigen Adressen aufgelöst werden. Um ein Label zu deklarieren, benutze `labelname:`. Diese können analog auch als Variablen benutzt werden. Weitere Informationen zur Anwendung sind in den Beispielprogrammen in [programs](programs/) zu finden.
+
+### Sektionen
+
+Assembly code ist in Sektionen unterteilt, „SECTION name“ leitet eine Sektion ein, die vom Assembler platziert wird, „SECTION name[@address]“ platziert die Sektion an der angegebenen Adresse. Da die Ausführung immer an Adresse 0 startet, sollte es eine Sektion geben, die explizit an Adresse 0 steht, um den Programmstart korrekt zu setzen (bspw. "SECTION main[@0]").
+
+Beispielassemblyprogramme finden Sie im Ordner [programs](programs/).
+
+
+## Simulator
+
+Can be run with `cabal run simulator -- [-v] [-p] <filename.asm|filename.cmm>`. The simulator takes assembled programs and executes them. Optional `-v` enables interactive debug mode with breakpoints, and `-p` enables line-wise output format showing each output value on a new line with its numeric representation.
+
+The simulator catches instructions like `OUT`, `PRNT`, `DOUT` and `STR` and prints them to console.
 
-Assemblycode ist in Sektionen unterteilt, „SECTION name“ leitet eine Sektion ein, die vom Assembler platziert wird, „SECTION name[@address]“ platziert die Sektion an der angegebenen Adresse. Da die Ausführung immer an Adresse 0 startet, sollte es eine Sektion geben, die explizit an Adresse 0 steht, um den Programmstart korrekt zu setzen.
+### Breakpoints
 
-Beispielassemblyprogramme finden Sie im Ordner Assembler/programs.
+Breakpoints can be set using the BRK instruction. Upon encountering a breakpoint, the simulator pauses execution, prints "BREAK" to the terminal, and allows you to debug the code (commands: `state`, `continue`, `exit`).