From 64c85ba0b872ff18015dce3aebeb0ac50d96ca4f Mon Sep 17 00:00:00 2001
From: Daniel Benusovich <flyingmonkeys1996@gmail.com>
Date: Fri, 8 Mar 2019 20:04:10 -0800
Subject: [PATCH] Add comments for AddressEncoder and associated tests

---
 TLB/src/AddressEncoder.py        | 16 ++++++++++++++++
 TLB/test/test_address_encoder.py | 26 +++++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/TLB/src/AddressEncoder.py b/TLB/src/AddressEncoder.py
index 53e2479e..59e92f95 100644
--- a/TLB/src/AddressEncoder.py
+++ b/TLB/src/AddressEncoder.py
@@ -2,7 +2,23 @@ from nmigen import Module, Signal
 from nmigen.lib.coding import Encoder, PriorityEncoder
 
 class AddressEncoder():
+    """Address Encoder
+    
+       The purpose of this module is to take in a vector and 
+       encode the bits that are one hot into an address. This module
+       combines both nmigen's Encoder and PriorityEncoder and will state
+       whether the input line has a single bit hot, multiple bits hot,
+       or no bits hot. The output line will always have the lowest value 
+       address output.
+       
+       Usage:
+       The output is valid when either single or multiple match is high.
+       Otherwise output is 0.
+    """
     def __init__(self, width):
+        """ Arguments:
+            * width: The desired length of the input vector
+        """
         # Internal
         self.encoder = Encoder(width)
         self.p_encoder = PriorityEncoder(width)
diff --git a/TLB/test/test_address_encoder.py b/TLB/test/test_address_encoder.py
index db555e12..8c3b6ad7 100644
--- a/TLB/test/test_address_encoder.py
+++ b/TLB/test/test_address_encoder.py
@@ -12,18 +12,42 @@ def set_encoder(dut, i):
     yield dut.i.eq(i)
     yield
     
+# Checks the single match of the AddressEncoder
+# Arguments:
+#   dut: The AddressEncoder being tested
+#   sm (Single Match): The expected match result
+#   op (Operation): (0 => ==), (1 => !=)
 def check_single_match(dut, sm, op):
     out_sm = yield dut.single_match
     assert_op("Single Match", out_sm, sm, op)
     
+# Checks the multiple match of the AddressEncoder
+# Arguments:
+#   dut: The AddressEncoder being tested
+#   mm (Multiple Match): The expected match result
+#   op (Operation): (0 => ==), (1 => !=)    
 def check_multiple_match(dut, mm, op):
     out_mm = yield dut.multiple_match
     assert_op("Multiple Match", out_mm, mm, op)
     
+# Checks the output of the AddressEncoder
+# Arguments:
+#   dut: The AddressEncoder being tested
+#   o (Output): The expected output
+#   op (Operation): (0 => ==), (1 => !=)
 def check_output(dut, o, op):
     out_o = yield dut.o
     assert_op("Output", out_o, o, op)
-    
+
+# Checks the state of the AddressEncoder
+# Arguments:
+#   dut: The AddressEncoder being tested
+#   sm (Single Match): The expected match result
+#   mm (Multiple Match): The expected match result
+#   o (Output): The expected output
+#   ss_op (Operation): Operation for the match assertion (0 => ==), (1 => !=)
+#   mm_op (Operation): Operation for the match assertion (0 => ==), (1 => !=)
+#   o_op (Operation): Operation for the match assertion (0 => ==), (1 => !=)
 def check_all(dut, sm, mm, o, sm_op, mm_op, o_op):
     yield from check_single_match(dut, sm, sm_op)
     yield from check_multiple_match(dut, mm, mm_op)
-- 
2.30.2