0.5.2

- (#77) Add support for wildcard bins. Both single and
  array bins are supported.

Signed-off-by: Matthew Ballance <[email protected]>

Author: mballance

doc/Changelog.md

@@ -1,4 +1,8 @@
 
+## 0.5.2
+- (#77) Add support for wildcard bins. Both single and
+  array bins are supported.
+
 ## 0.5.1
 - Adjust the debug approach to collect singles, pairs,
   triples of failing constraints.

doc/source/coverage.rst

@@ -208,6 +208,69 @@ a callable is providing the target value. Consequently, the cp_t
 parameter is used to specify that the value being sampled is an 8-bit
 unsigned integer.
 
+Wildcard Bins (Single)
+^^^^^^^^^^^^^^^^^^^^^^
+A wildcard specification may be used to specify the values within 
+single bins. The checked value may either be specified as a string
+that contains wildcard characters ('x', '?') or may be specified
+as a tuple of (value, mask).
+
+When using the string form of specifying a wildcard bin, the 
+specification string must start with "0x" (hexadecimal), 
+"0o" (octal), or "0b" (binary).
+
+Here is an example showing specification of a wildcard bin that 
+matches any value 0x80..0x8F:
+
+.. code-block:: python3
+
+        @vsc.covergroup
+        class cg(object):
+            
+            def __init__(self):
+                self.with_sample(
+                    dict(a=vsc.bit_t(8)))
+                
+                self.cp_a = vsc.coverpoint(self.a, bins=dict(
+                    a=vsc.wildcard_bin("0x8x")))
+
+Here is the same coverpoint specification using the value/mask
+form:
+
+.. code-block:: python3
+
+        @vsc.covergroup
+        class cg(object):
+            
+            def __init__(self):
+                self.with_sample(
+                    dict(a=vsc.bit_t(8)))
+                
+                self.cp_a = vsc.coverpoint(self.a, bins=dict(
+                    a=vsc.wildcard_bin((0x80,0xF0))
+                    ))
+
+Wildcard Bins (Array)
+^^^^^^^^^^^^^^^^^^^^^                    
+A wildcard specification may also be used to specify arrays of bins.
+In this case, the wildcard characters specify a location where all
+possibilities must be expanded.
+
+The example below creates 16 bins for the values 0x80..0x8F:
+
+.. code-block:: python3
+
+        @vsc.covergroup
+        class cg(object):
+            
+            def __init__(self):
+                self.with_sample(
+                    dict(a=vsc.bit_t(8)))
+                
+                self.cp_a = vsc.coverpoint(self.a, bins=dict(
+                    a=vsc.wildcard_bin_array([], "0x8x")
+                    ))
+
 Coverpoint Crosses
 ------------------
 

etc/ivpm.info

@@ -1,4 +1,4 @@
 
 name=pyvsc
-version=0.5.1
+version=0.5.2
 

src/vsc/coverage.py

@@ -47,6 +47,9 @@
 from vsc.model.source_info import SourceInfo
 from vsc.types import rangelist, bit_t, to_expr, type_base, enum_t, type_enum, \
     expr, field_info
+from vsc.impl.wildcard_bin_factory import WildcardBinFactory
+from vsc.model.coverpoint_bin_single_wildcard_model import CoverpointBinSingleWildcardModel
+from vsc.model.wildcard_binspec import WildcardBinspec
 
 
 def covergroup(T):
@@ -437,6 +440,138 @@ def build_cov_model(self, parent, name):
 
         return ret
 
+class wildcard_bin(object):
+    """Specifies a single wildcard coverage bin"""
+    def __init__(self, *args):
+        # Capture the declaration location of this bin
+        self.srcinfo_decl = SourceInfo.mk()
+
+        self.range_l = []        
+        for a in args:
+            if isinstance(a, tuple):
+                # Expressed in mask form
+                # (value, mask) where 1-bits in mask are compared and 0-bits are ignored
+                self.range_l.append(a)
+            elif isinstance(a, str):
+                # Expressed in string form in either oct, hex, or bin format
+                # 
+                value, mask = WildcardBinFactory.str2bin(a)
+                self.range_l.append((value,mask))
+            else:
+                raise Exception("Unknown argument %s to wildcard bin. Expect tuple or string" % (
+                    str(a)))
+        
+    def build_cov_model(self, parent, name):
+        ret = CoverpointBinSingleWildcardModel(
+            name, 
+            WildcardBinspec(self.range_l))
+        ret.srcinfo_decl = self.srcinfo_decl
+        
+        return ret    
+
+class wildcard_bin_array(object):
+    """Specifies an array of bins using wildcard specifications"""
+    
+    def __init__(self, nbins, *args):
+        """
+        args may be one of two formats
+        - Single list of wildcard strings (eg "0x82x")
+        - Single list of value/mask tuples (eg [(0x820,0xFF0)])
+        - Single string
+        - Single tuple
+        """
+        self.nbins = nbins
+        self.range_l = []
+        
+        # Convert the specification into canonical form: list of tuples
+        if len(args) == 1:
+            if isinstance(args[0], str):
+                value, mask = WildcardBinFactory.str2bin(args[0])
+                self.range_l.extend(WildcardBinFactory.valmask2binlist(value, mask))
+            elif isinstance(args[0], (list,tuple)):
+                # value/mask
+                if len(args[0]) != 2:
+                    raise Exception("Wildcard bin specification requires two elements (value,mask)")
+                
+                self.range_l.extend(WildcardBinFactory.valmask2binlist(args[0][0], args[0][1]))
+            else:
+                raise Exception("Bin specification " + str(args[0]) + " is neither string nor value/mask")
+            pass
+        else:
+            # Multiple arguments. Expect each to be a single-level string or tuple
+            for a in args:
+                if isinstance(a,(list,tuple)):
+                    if len(a) != 2:
+                        raise Exception("Wildcard bin range " + str(a) + " must have two elements")
+                    else:
+                        self.range_l.extend(WildcardBinFactory.valmask2binlist(a[0], a[1]))
+                elif isinstance(a,str):
+                    value, mask = WildcardBinFactory.str2bin(a)
+                    self.range_l.extend(WildcardBinFactory.valmask2binlist(value, mask))
+                else:
+                    raise Exception("Wildcard bin specification " + str(a) + " is neither value nor range")
+                
+        # TODO: handle overlap
+        self.range_l.sort(key=lambda e: e[0])
+        
+        # Now, collapse overlaps
+        i=0
+        while i < len(self.range_l):
+            if i+1 < len(self.range_l) and self.range_l[i][1]+1 >= self.range_l[i][0]:
+                self.range_l[i][1] = self.range_l[i+1][1]
+                self.range_l.pop(i+1)
+            else:
+                i += 1
+
+        if isinstance(nbins,list):
+            if len(nbins) not in (0,1):
+                raise Exception("Only 0 or 1 argument can be specified to the nbins argument")
+            self.nbins = -1 if len(nbins) == 0 else nbins[0]
+        else:
+            self.nbins = int(nbins)
+        
+        if len(args) == 0:
+            raise Exception("No bins range specified")
+        
+        # Capture the declaration location of this bin
+        frame = inspect.stack()[1]
+        self.srcinfo_decl = SourceInfo(frame.filename, frame.lineno)
+    
+    def build_cov_model(self, parent, name):
+        ret = None
+
+        # First, need to determine how many total bins
+        # Construct a range model
+        if self.nbins == -1:
+            # unlimited number of bins
+            if len(self.range_l) == 1:
+                r = self.range_l[0]
+                ret = CoverpointBinArrayModel(name, 0, r[0], r[1])
+            else:
+                idx=0
+                ret = CoverpointBinCollectionModel(name)
+                for r in self.range_l:
+                    if len(r) == 2:
+                        b = ret.add_bin(CoverpointBinArrayModel(name, idx, r[0], r[1]))
+                        b.srcinfo_decl = self.srcinfo_decl
+                        idx += ((r[1] - r[0]) + 1)
+                    elif len(r) == 1:
+                        b = ret.add_bin(CoverpointBinSingleValModel(name + "[" + str(idx) + "]", r[0]))
+                        b.srcinfo_decl = self.srcinfo_decl
+                        idx += 1
+                    else:
+                        raise Exception("Internal error: expect bin to have 1 or 2 elements not " + 
+                                        str(len(r)) + " (" +
+                                        name + " " + self.srcinfo_decl.filename + ":" +
+                                        str(self.srcinfo_decl.lineno) + ")")
+        else:
+            ret = CoverpointBinCollectionModel.mk_collection(name, 
+                    RangelistModel(self.range_l), self.nbins)
+        
+        ret.srcinfo_decl = self.srcinfo_decl
+
+        return ret
+        
 class binsof(object):
     # TODO: future implementation of the 'binsof' operator
 

src/vsc/impl/wildcard_bin_factory.py

@@ -0,0 +1,92 @@
+'''
+Created on Jul 23, 2021
+
+@author: mballance
+'''
+
+
+class WildcardBinFactory(object):
+    
+    @classmethod
+    def str2bin(cls, val) -> tuple:
+        # val is string in oct, hex, or bin
+
+        value = 0
+        mask = 0
+        
+        if val.startswith("0o") or val.startswith("0O"):
+            # octal format
+            for c in val[2:]:
+                if c != '_':
+                    value <<= 3
+                    mask <<= 3
+                    if c not in ['x', 'X', '?']:
+                        mask |= 0x7
+                        value |= int(c, 8)
+        elif val.startswith("0x") or val.startswith("0X"):
+            for c in val[2:]:
+                if c != '_':
+                    value <<= 4
+                    mask <<= 4
+                    if c not in ['x', 'X', '?']:
+                        mask |= 0xF
+                        value |= int(c, 16)
+        elif val.startswith("0b") or val.startswith("0B"):
+            for c in val[2:]:
+                if c != '_':
+                    value <<= 1
+                    mask <<= 1
+                    if c not in ['x', 'X', '?']:
+                        mask |= 0x1
+                        value |= int(c, 2)
+        else:
+            raise Exception("unknown base for value %s" % str(val))
+        
+        return (value,mask)
+    
+    @classmethod
+    def valmask2binlist(cls, value, mask):
+        """Converts value/mask representation to a list of bin specifications"""
+        
+        n_bits = 0
+        
+        mask_t = mask
+        bit_i = 0
+
+        total_mask_bits = 0
+        directives = []
+        while mask_t != 0:
+            if (mask_t & 1) == 0:
+                # Collect this grouping
+                group_start_bit = bit_i
+                group_n_bits = 0
+                while (mask_t & 1) == 0:
+                    group_n_bits += 1
+                    total_mask_bits += 1
+                    mask_t >>= 1
+                    bit_i += 1
+                    pass
+                directives.append((group_start_bit, group_n_bits))
+            else:
+                mask_t >>= 1
+                bit_i += 1
+                
+        if total_mask_bits > 20:
+            raise Exception("Wildcard array bins limited to 20 mask bits")
+
+        ranges = []
+        for val in range(0, (1 << total_mask_bits)):
+
+            val_i = val
+            val_t = (value & mask)
+            for d in directives:
+                val_t |= ((val_i & ((1 << d[1])-1)) << d[0])
+                val_i >>= d[1]
+                
+            if len(ranges) > 0 and ranges[-1][1]+1 == val_t:
+                ranges[-1] = (ranges[-1][0], val_t)
+            else:  
+                ranges.append((val_t, val_t))
+                    
+        return ranges
+

src/vsc/model/coverpoint_bin_single_wildcard_model.py

@@ -0,0 +1,53 @@
+'''
+Created on Jul 23, 2021
+
+@author: mballance
+'''
+from vsc.model.coverpoint_bin_model_base import CoverpointBinModelBase
+from vsc.model.wildcard_binspec import WildcardBinspec
+
+class CoverpointBinSingleWildcardModel(CoverpointBinModelBase):
+    
+    def __init__(self, name, specs : WildcardBinspec):
+        super().__init__(name)
+        self.n_bins = 1
+        self.wildcard_binspec = specs
+        pass
+    
+    def finalize(self, bin_idx_base : int) -> int:
+        super().finalize(bin_idx_base)
+        return 1
+    
+    def get_bin_expr(self, bin_idx):
+        pass
+    
+    def get_bin_name(self, bin_idx):
+        return self.name
+    
+    def sample(self):
+        val = int(self.cp.get_val())
+
+        # Process each value/mask pair
+        self.hit_bin_idx = -1        
+        for s in self.wildcard_binspec.specs:
+            if (val & s[1]) == s[0]:
+                self.hit_bin_idx = 0
+                self.cp.coverage_ev(self.bin_idx_base)
+                break
+        
+        
+    def accept(self, v):
+        v.visit_coverpoint_bin_single_wildcard(self)
+        
+    def equals(self, oth) -> bool:
+        eq = isinstance(oth, CoverpointBinSingleWildcardModel)
+        
+        if eq:
+            eq &= self.wildcard_binspec.equals(oth.wildcard_binspec)
+            
+        return eq
+    
+    def clone(self):
+        return CoverpointBinSingleWildcardModel(
+            self.name, 
+            self.wildcard_binspec.clone())

src/vsc/model/model_visitor.py

@@ -45,6 +45,7 @@
 from vsc.model.constraint_inline_scope_model import ConstraintInlineScopeModel
 from vsc.model.expr_dynamic_model import ExprDynamicModel
 from vsc.model.constraint_solve_order_model import ConstraintSolveOrderModel
+from vsc.model.coverpoint_bin_single_wildcard_model import CoverpointBinSingleWildcardModel
 
 
 
@@ -248,6 +249,9 @@ def visit_coverpoint_bin_collection(self, bn : CoverpointBinCollectionModel):
 
     def visit_coverpoint_bin_single_range(self, bn : CoverpointBinSingleRangeModel):
         pass
+    
+    def visit_coverpoint_bin_single_wildcard(self, bn : CoverpointBinSingleWildcardModel):
+        pass
 
     def visit_coverpoint_bin_enum(self, bn : CoverpointBinEnumModel):
         pass