Update chapter 3 bootcamp (#333)

Author: quekyj

doc/tutorials/README.md

@@ -36,6 +36,7 @@
 - [Introduction to Test Driven Development](./chapter_3/00_unit_test.md#introduction-to-test-driven-development)
 - [What is a Full-Adder?](./chapter_3/00_unit_test.md#what-is-a-full-adder)
 - [Create a Full-Adder with TDD](./chapter_3/00_unit_test.md#create-full-adder-with-tdd)
+- [Exercise](./chapter_3/00_unit_test.md#exercise)
 
 ## Chapter 4: Basic Generation
 

doc/tutorials/chapter_3/00_unit_test.md

@@ -3,6 +3,7 @@
 - [Introduction to Test Driven Development](./00_unit_test.md#introduction-to-test-driven-development)
 - [What is a Full-Adder?](./00_unit_test.md#what-is-a-full-adder)
 - [Create a Full-Adder with TDD](./00_unit_test.md#create-full-adder-with-tdd)
+- [Exercise](./00_unit_test.md#exercise)
 
 ## Learning Outcome
 
@@ -18,7 +19,7 @@ TDD is a software development approach in which test cases are created to specif
 
 ## What is a Full-Adder?
 
-A Full Adder is an adder that takes three inputs and produces two outputs: the first two inputs are A and B, while the third input is a carry-in (C-IN). The output carry is designated as C-OUT, while the normal output is designated as S (SUM). A Full Adder logic is designed to handle up to eight inputs to create a byte-wide adder and can cascade the carry bit from one adder to another. We use a Full Adder when a carry-in bit is available because a 1-bit half-adder cannot take a carry-in bit, and another 1-bit adder must be used instead. A 1-bit Full Adder adds three operands and generates a 2-bit result.
+A Full Adder is an adder that takes three inputs and produces two outputs: the first two inputs are A and B, while the third input is a carry-in (C-IN). The output carry is designated as C-OUT, while the normal output is designated as S (SUM). We use a Full Adder when a carry-in bit is available because a 1-bit half-adder cannot take a carry-in bit, and another 1-bit adder must be used instead. A 1-bit Full Adder adds three operands and generates a 2-bit result.
 
 Below is the circuit diagram of full-adder. From the diagram, we can see that the output `SUM` is the result of `XOR(XOR(A, B), C-IN)`, while `C-Out` is the result of `OR(AND(C-IN, XOR(A, B)), AND(B, A))`.
 
@@ -147,3 +148,9 @@ test('should return true if result c-out is similar to truth table.', () async {
 ```
 
 Yeah, thats it. Congratulations! We have now successfully created a Full-Adder. You can find the executable code at [full_adder.dart](./full_adder.dart).
+
+## Exercise
+
+1. Based on what you learn, build a [Full Subtractor](https://www.geeksforgeeks.org/full-subtractor-in-digital-logic).
+
+Answer to this exercise can be found at [answers/exercise.dart](./answers/exercise.dart). For those who wish to see the answer implementation with system verilog, you can check at [answers/exercise_sv.dart](./answers/exercise_sv.dart).

doc/tutorials/chapter_3/answers/exercise.dart

@@ -0,0 +1,38 @@
+import 'package:rohd/rohd.dart';
+import 'package:test/test.dart';
+import 'helper.dart';
+
+void main() async {
+  final a = Logic(name: 'a');
+  final b = Logic(name: 'b');
+  final borrowIn = Logic(name: 'borrow_in');
+
+  final xorAB = a ^ b;
+  final diff = xorAB ^ borrowIn;
+  final borrowOut = (~xorAB & borrowIn) | (~a & b);
+
+  test('should return 0 when a and b equal 1', () async {
+    a.put(1);
+    b.put(1);
+    borrowIn.put(0);
+
+    expect(diff.value.toInt(), equals(0));
+  });
+
+  test('should return true if results matched truth table', () async {
+    for (var i = 0; i <= 1; i++) {
+      for (var j = 0; j <= 1; j++) {
+        for (var k = 0; k <= 1; k++) {
+          a.put(i);
+          b.put(j);
+          borrowIn.put(k);
+
+          final res = fsTruthTable(i, j, k);
+
+          expect(diff.value.toInt(), res.diff);
+          expect(borrowOut.value.toInt(), res.borrowOut);
+        }
+      }
+    }
+  });
+}

doc/tutorials/chapter_3/answers/exercise_sv.dart

@@ -0,0 +1,62 @@
+import 'package:rohd/rohd.dart';
+import 'package:test/test.dart';
+import 'helper.dart';
+
+class FullSubtractor extends Module {
+  FullSubtractor(Logic a, Logic b, Logic borrowIn)
+      : super(name: 'full_subtractor') {
+    // Add Input
+    a = addInput('a', a);
+    b = addInput('b', b);
+    borrowIn = addInput('borrowIn', borrowIn);
+
+    // Add Output
+    final borrowOut = addOutput('borrowOut');
+    final diff = addOutput('diff');
+
+    // Logic
+    final xorAB = a ^ b;
+    diff <= xorAB ^ borrowIn;
+    borrowOut <= (~xorAB & borrowIn) | (~a & b);
+  }
+  // getter for output
+  Logic get borrowOut => output('borrowOut');
+  Logic get diff => output('diff');
+}
+
+void main() async {
+  final a = Logic(name: 'a');
+  final b = Logic(name: 'b');
+  final borrowIn = Logic(name: 'borrow_in');
+
+  final fSub = FullSubtractor(a, b, borrowIn);
+  await fSub.build();
+
+  // ignore: avoid_print
+  print(fSub.generateSynth());
+
+  test('should return 0 when a and b equal 1', () async {
+    a.put(1);
+    b.put(1);
+    borrowIn.put(0);
+
+    expect(fSub.diff.value.toInt(), equals(0));
+  });
+
+  test('should return true if results matched truth table', () async {
+    for (var i = 0; i <= 1; i++) {
+      for (var j = 0; j <= 1; j++) {
+        for (var k = 0; k <= 1; k++) {
+          a.put(i);
+          b.put(j);
+          borrowIn.put(k);
+
+          final res = fsTruthTable(i, j, k);
+
+          expect(fSub.diff.value.toInt(), res.diff);
+          expect(fSub.borrowOut.value.toInt(), res.borrowOut);
+        }
+      }
+    }
+  });
+}

doc/tutorials/chapter_3/answers/helper.dart

@@ -0,0 +1,18 @@
+class FSResult {
+  int diff = 0;
+  int borrowOut = 0;
+}
+
+FSResult fsTruthTable(int a, int b, int bIn) {
+  final res = FSResult();
+
+  if (a < b + bIn) {
+    res
+      ..diff = (a + 2) - b - bIn
+      ..borrowOut = 1;
+  } else {
+    res.diff = a - b - bIn;
+  }
+
+  return res;
+}

doc/tutorials/chapter_3/full_adder.dart

@@ -43,7 +43,12 @@ void main() async {
           b.put(j);
           cIn.put(k);
 
-          expect(sum.value.toInt(), faTruthTable(i, j, k).sum);
+          final expected = faTruthTable(i, j, k).sum;
+          final actual = sum.value.toInt();
+
+          expect(actual, expected,
+              reason: 'For inputs a=$i, b=$j, cIn=$k,'
+                  ' expected sum=$expected but found $actual');
         }
       }
     }
@@ -58,7 +63,12 @@ void main() async {
           b.put(j);
           cIn.put(k);
 
-          expect(cOut.value.toInt(), faTruthTable(i, j, k).cOut);
+          final expected = faTruthTable(i, j, k).cOut;
+          final actual = cOut.value.toInt();
+
+          expect(actual, expected,
+              reason: 'For inputs a=$i, b=$j, cIn=$k,'
+                  ' expected sum=$expected but found $actual');
         }
       }
     }