Merge branch 'master' into pseudo-ops-support

riscv_isac/coverage.py

@@ -3,7 +3,6 @@
 # See LICENSE.iitm for details
 
 from itertools import islice
-from time import sleep
 import ruamel
 from ruamel.yaml import YAML
 import riscv_isac.utils as utils
@@ -21,6 +20,7 @@
 import riscv_isac.plugins as plugins
 from riscv_isac.plugins.specification import *
 import math
+from itertools import islice
 import multiprocessing as mp
 from collections.abc import MutableMapping
 
@@ -535,7 +535,7 @@ def compute_per_line(queue, event, cgf_queue, stats_queue, cgf, xlen, addr_pairs
     '''
     This function checks if the current instruction under scrutiny matches a
     particular coverpoint of interest. If so, it updates the coverpoints and
-    return the same.
+    returns the same.
 
     :param queue: A queue thread to push instructionObject
     :param event: Event object to signal completion of decoding
@@ -568,7 +568,11 @@ def compute_per_line(queue, event, cgf_queue, stats_queue, cgf, xlen, addr_pairs
     hit_covpts = []
     rcgf = copy.deepcopy(cgf)
 
+    # Enter the loop only when Event is not set or when the 
+    # instruction object queue is not empty 
     while (event.is_set() == False) or (queue.empty() == False):
+
+        # If there are instructions in queue, compute coverage
         if queue.empty() is False:
 
             instr = queue.get_nowait()
@@ -979,11 +983,14 @@ def compute_per_line(queue, event, cgf_queue, stats_queue, cgf, xlen, addr_pairs
                 else:
                     hit_covpts = []
     else:
+        # if no_count option is set, return rcgf
+        # else return cgf
         if not no_count:
             cgf_queue.put_nowait(cgf)
         else:
             cgf_queue.put_nowait(rcgf)
 
+        # Pass statistics back to main process
         stats_queue.put_nowait(stats)
         cgf_queue.close()
         stats_queue.close()
@@ -1056,26 +1063,26 @@ def compute(trace_file, test_name, cgf, parser_name, decoder_name, detailed, xle
 
     iterator = iter(parser.__iter__()[0])
 
-    # If number of processors to be spawned is more than that available
+
+    # If number of processes to be spawned is more than that available,
+    # allot number of processes to be equal to one less than maximum
     available_cores = mp.cpu_count()
     if procs > available_cores:
         procs = available_cores - 1
-
-    # Partiton cgf to chunks
-    chunk_len = math.ceil(len(cgf) / procs)
-    chunks = [{k:cgf[k] for k in islice(iter(cgf), chunk_len)} for i in range(0, len(cgf), chunk_len)]
 
     # Partiton cgf to chunks
     chunk_len = math.ceil(len(cgf) / procs)
     chunks = [{k:cgf[k] for k in islice(iter(cgf), chunk_len)} for i in range(0, len(cgf), chunk_len)]
 
-    queue_list = []
-    process_list = []
-    event_list = []
-    cgf_queue_list = []
-    stats_queue_list = []
+    queue_list = []                     # List of queues to pass instructions to daughter processes
+    process_list = []                   # List of processes to be spawned
+    event_list = []                     # List of Event objects to signal exhaustion of instruction list to daughter processes
+    cgf_queue_list = []                 # List of queues to retrieve the updated CGF dictionary from each processes
+    stats_queue_list = []               # List of queues to retrieve coverpoint hit statistics from each processes
 
-    #Initialize processes and queues
+    # For each chunk of cgf dictionary, spawn a new queue thread to pass instrObj,
+    # to retrieve updated cgf, to retrieve statistics. An Event object is appended for
+    # each processes spawned. A Process object is appended against every cgf chunk and initialized.
     for i in range(len(chunks)):
         queue_list.append(mp.Queue())
         cgf_queue_list.append(mp.Queue())
@@ -1093,19 +1100,21 @@ def compute(trace_file, test_name, cgf, parser_name, decoder_name, detailed, xle
                                     )
                             )
                         )
-    #Start processes
+    #Start each processes
     for each in process_list:
         each.start()
-    queue_time = 0
+
+    # This loop facilitates parsing, disassembly and generation of instruction objects
     for instrObj_temp in iterator:
         instr = instrObj_temp.instr
         if instr is None:
             continue
         instrObj = (decoder.decode(instrObj_temp = instrObj_temp))[0]
 
-        # Pass instrObjs to queue
+        # Pass instrObjs to queues pertaining to each processes
         for each in queue_list:
             each.put_nowait(instrObj)
+
         logger.debug(instrObj)
         cross_cover_queue.append(instrObj)
         if(len(cross_cover_queue)>=window_size):