From 6ac5d8ff63cd00b08e44171bee0b96d7d1334b77 Mon Sep 17 00:00:00 2001
From: Erick <ahmederick00@gmail.com>
Date: Mon, 7 Mar 2022 02:16:50 +0100
Subject: [PATCH] Update README.md

---
 README.md | 101 +++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 65 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index 046f357..dc2c25b 100644
--- a/README.md
+++ b/README.md
@@ -9,58 +9,87 @@ Most of the gates also have a 16-bit version and eventually a n-way version (som
 
 Ex: a 4-way mux gate:
 
-    module mux4way(out, i0, i1, i2, i3, sel0, sel1);
-        input i0, i1, i2, i3;
-        input [3:0]sel;
-        output [3:0]out;
-        wire tmp0, tmp1, tmp2, tmp3;
+'''
+module mux4way(out, i0, i1, i2, i3, sel0, sel1);
+    input i0, i1, i2, i3;
+    input [3:0]sel;
+    output [3:0]out;
+    wire tmp0, tmp1, tmp2, tmp3;
 
-        wire [3:0] [1:0] sel0 = sel;
-        wire [0:3] [1:0] sel1 = sel;
+    wire [3:0] [1:0] sel0 = sel;
+    wire [0:3] [1:0] sel1 = sel;
 
-        not(notSel0, sel0);
-        not(notSel1, sel1);
+    not(notSel0, sel0);
+    not(notSel1, sel1);
 
-        and(tmp0, i0, notSel0);
-        and(tmp1, i1, sel0);
-        and(tmp2, i2, notSel1);
-        and(tmp3, i3, sel1);
+    and(tmp0, i0, notSel0);
+    and(tmp1, i1, sel0);
+    and(tmp2, i2, notSel1);
+    and(tmp3, i3, sel1);
 
-        or4way(out, tmp0, tmp1, tmp2, tmp3);
+    or4way(out, tmp0, tmp1, tmp2, tmp3);
 
-    endmodule
+endmodule
+'''
 
 #### Predefined gates (path: /gates/predefined)
 The predefined gates are by default implemented on Verilog/Systemverilog. Thus they are not strictly needed for building more advanced gates or chipset, but I still decided to add them as reference and learning purposes.
 
 #### Testbenches (path: /testbenches)
-Testbenches are a way to test the implementation of a particular gate using a Verilog compiler
-
-Ex: testbench for a xor gate:
-
-    module xor_tb();
-        reg ta, tb;
-        wire ty;
-
-        xor_gate dut(y, ta, tb);
-
-        initial begin
-            ta=0, tb=0;
-            $monitor("IN: %b, %b ",ta, tb, "OUT: ",y);
-            ta=0, tb=1;
-            $monitor("IN: %b, %b ",ta, tb, "OUT: ",y);
-            ta=1, tb=0;
-            $monitor("IN: %b, %b ",ta, tb, "OUT: ",y);
-            ta=1, tb=1;
-        end
-    endmodule
+Testbenches are a way to test the implementation of a particular gate using a Verilog compiler. They output a set of I/O command to test the correct implementation of a given gate.
 
 ### Arithmetic Logic Unit (path: /alu)
-The ALU is written is Systemverilog (such as the CPU and other complex components). It handles 16-bit values and performs numerous operations, as:
+The ALU is written is Systemverilog (such as the CPU and other complex components). It handles two 16-bit inputs, a 6-bit opcode and a 16-bit output and a 2-bit sign flag. It computes the following instructions:
 
+    x+y
+    x-y
+    y-x
+    0
+    1
+    -1
+    x
+    y
+    -x
+    -y
+    !x
+    !y
+    x+1
+    y+1
+    x-1
+    y-1
+    x&y
+    x|y
 
+The 6-bit opcode gets divided in single bits and refered to as:
+    za
+    na
+    zb
+    nb
+    f
+    no
+
+The ALU logic manipulates the a and b inputs and operates on the resulting values, and in the exact order as it follows, thus permitting to make all of the 16 operations described before:
+
+* if (za == 1) set x = 0            16-bit constant
+* if (na == 1) set x = !x           bitwise not
+* if (zb == 1) set y = 0            16-bit constant
+* if (nb == 1) set y = !y           bitwise not
+* if (f == 1)  set out = x + y      integer 2's complement addition
+* if (f == 0)  set out = x & y      bitwise and
+* if (no == 1) set out = !out       bitwise not
+
+And the 2-bit sign flag is:
+    0 (if output < 0)
+    1 (if output = 0)
+    2 (if output > 0)
 
 ## Usage
+#### Verilog/Systemverilog logic gates
+To run any Verilog (.v) or Systemverilog (.sv) file, use *iverilog* (available for Windows, Linux and MacOS) using the command:
+    >> iverilog filename.v
+
+To visually see the functioning of a gate and it's testbench you need to use *gtkwave* and have a .vcd file of the gate (plus eventually the testbench, in the same file):
+    >> gtkwave filename.vcd
 
 ## Resources
 - Online Verilog Compiler:  https://www.tutorialspoint.com/compile_verilog_online.php