covsight-core 0.1.2__py3-none-any.whl

covsight/core/__init__.py

@@ -0,0 +1,13 @@
+"""
+covsight-core: UCIS data-model API, in-memory backend, and NCDB format.
+
+Quick-start::
+
+    from covsight.core.mem import MemFactory
+    from covsight.core.api import ScopeTypeT, SourceT, CoverData
+
+    db = MemFactory.create()
+    cg = db.createScope("my_cg", None, 1, SourceT.SV,
+                        ScopeTypeT.COVERGROUP, 0)
+    db.close()
+"""

covsight/core/api/__init__.py

@@ -0,0 +1,32 @@
+# Abstract interfaces
+from covsight.core.api.obj import Obj
+from covsight.core.api.scope import Scope
+from covsight.core.api.ucis import UCIS
+from covsight.core.api.history_node import HistoryNode
+from covsight.core.api.cov_scope import CovScope
+from covsight.core.api.cvg_scope import CvgScope
+from covsight.core.api.du_scope import DUScope
+from covsight.core.api.instance_scope import InstanceScope
+from covsight.core.api.covergroup import Covergroup
+from covsight.core.api.coverpoint import Coverpoint
+from covsight.core.api.cross import Cross
+from covsight.core.api.cover_item import CoverItem
+from covsight.core.api.cover_type import CoverType
+from covsight.core.api.instance_coverage import InstanceCoverage
+
+# Data classes
+from covsight.core.api.source_info import SourceInfo
+from covsight.core.api.cover_data import CoverData
+from covsight.core.api.cover_index import CoverIndex
+from covsight.core.api.file_handle import FileHandle
+from covsight.core.api.test_data import TestData
+from covsight.core.api.source_file import SourceFile
+from covsight.core.api.statement_id import StatementId
+
+# All enums
+from covsight.core.api.enums import (
+    ScopeTypeT, CoverTypeT, CoverFlagsT, FlagsT, SourceT,
+    ToggleMetricT, ToggleTypeT, ToggleDirT,
+    HistoryNodeKind, IntProperty, StrProperty, RealProperty,
+    HandleProperty, TestStatusT, FormalStatusT,
+)

covsight/core/api/cov_scope.py

@@ -0,0 +1,70 @@
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+'''
+Created on Jan 8, 2020
+
+@author: ballance
+'''
+from covsight.core.api.scope import Scope
+
+class CovScope(Scope):
+    """Base class for generic coverage scopes.
+    
+    CovScope is the base class for all coverage-related scopes in the UCIS
+    hierarchy. It sits between the generic Scope class and more specialized
+    coverage scope types like FuncCovScope (functional coverage) and code
+    coverage scopes.
+    
+    CovScope provides common infrastructure for coverage scopes but adds
+    minimal functionality beyond the base Scope class. It serves primarily
+    as a structural marker in the type hierarchy to distinguish coverage
+    scopes from non-coverage scopes (like pure structural scopes).
+    
+    Subclass hierarchy:
+        Scope
+        └── CovScope (this class)
+            ├── FuncCovScope (functional coverage)
+            │   └── CvgScope (covergroups/coverpoints)
+            └── (Code coverage scopes)
+    
+    Note:
+        CovScope is rarely instantiated directly. Use specific subclasses
+        like Covergroup, Coverpoint, or code coverage scope types instead.
+        
+    Example:
+        >>> # CovScope is not directly used; use subclasses instead
+        >>> # For functional coverage:
+        >>> cg = design.createCovergroup("cg_bus", src_info, 1, SourceT.SV)
+        >>>
+        >>> # For code coverage:
+        >>> instance = design.createInstance("u_core", src_info, 1, SourceT.SV, "core")
+        
+    See Also:
+        Scope: Base scope class
+        FuncCovScope: Functional coverage base
+        CvgScope: Covergroup scope base
+        InstanceScope: Design instance scope
+    """
+    
+    def __init__(self):
+        
+        pass
+    
+    
+    

covsight/core/api/cover_data.py

@@ -0,0 +1,88 @@
+'''
+Created on Jan 11, 2020
+
+@author: ballance
+'''
+from covsight.core.api.enums import CoverTypeT
+
+class CoverData():
+    """Container for coverage measurement data.
+    
+    CoverData encapsulates all measurement values associated with a coverage
+    item (bin), including the hit count, goal, weight, and limit. It serves as
+    a data transfer object when creating or querying cover items.
+    
+    Coverage data consists of:
+    - **data**: The actual hit count (how many times the item was covered)
+    - **goal**: Target count for considering the item "covered"
+    - **weight**: Relative importance in coverage calculations
+    - **limit**: Maximum count before saturation (coverage stops incrementing)
+    - **type**: Coverage type (CVGBIN, BRANCHBIN, TOGGLEBIN, etc.)
+    - **flags**: Behavioral flags (data format, has_goal, has_weight, etc.)
+    
+    The flags determine which fields are valid and how data is interpreted.
+    For example, HAS_GOAL flag indicates the goal field is meaningful.
+    
+    Attributes:
+        type (CoverTypeT): Coverage type identifying the metric category.
+        flags (CoverFlagsT): Bitwise flags controlling data interpretation.
+        data (int): Hit count - number of times this coverage item was hit.
+        goal (int): Target count for coverage completion (if HAS_GOAL flag set).
+        weight (int): Relative weight for coverage computation (if HAS_WEIGHT flag set).
+        limit (int): Count saturation limit (if HAS_LIMIT flag set).
+        bitlen (int): Bit length for vector data (if IS_VECTOR flag set).
+        
+    Example:
+        >>> from covsight.core.api.enums import CoverFlagsT
+        >>> # Simple bin with goal and weight
+        >>> data = CoverData(
+        ...     type=CoverTypeT.CVGBIN,
+        ...     flags=CoverFlagsT.HAS_GOAL | CoverFlagsT.HAS_WEIGHT)
+        >>> data.goal = 1
+        >>> data.weight = 1
+        >>> data.data = 0  # Not yet hit
+        >>> 
+        >>> # Use when creating cover item
+        >>> idx = coverpoint.createNextCover("bin_low", data, src_info)
+        
+    Note:
+        Default values (0) are set for all fields. Set flags appropriately to
+        indicate which fields contain valid data. Tools may ignore fields whose
+        corresponding flags are not set.
+        
+    See Also:
+        Scope.createNextCover(): Create cover items with this data
+        CoverTypeT: Coverage type enumeration
+        CoverFlagsT: Coverage data flags
+        UCIS LRM Section 8.11.3 "ucis_GetCoverData"
+        UCIS LRM Section 8.11.4 "ucis_SetCoverData"
+    """
+    
+    def __init__(self,
+                 type : CoverTypeT,
+                 flags):
+        """Create coverage data container.
+        
+        Args:
+            type: Coverage type (CoverTypeT enum) indicating metric category.
+            flags: Bitwise OR of CoverFlagsT flags controlling data interpretation.
+                Common flags: HAS_GOAL, HAS_WEIGHT, HAS_LIMIT, IS_32BIT, IS_64BIT.
+                
+        Example:
+            >>> # Covergroup bin with goal and weight
+            >>> data = CoverData(CoverTypeT.CVGBIN, 
+            ...                  CoverFlagsT.HAS_GOAL | CoverFlagsT.HAS_WEIGHT)
+            >>> # Branch coverage with just count
+            >>> data = CoverData(CoverTypeT.BRANCHBIN, 0)
+        """
+        self.type = type
+        self.flags = flags
+        # TODO: determine default data based on flags
+        self.data = 0
+        self.goal = 0 # if UCIS_HAS_GOAL
+        self.weight = 0 # if UCIS_HAS_WEIGHT
+        self.limit = 0 # if UCIS_HAS_LIMIT
+        self.bitlen = 0 # if bytevector
+        self.at_least = 1 # Minimum count for coverage (default 1)
+                 
+            

covsight/core/api/cover_index.py

@@ -0,0 +1,157 @@
+'''
+Created on Mar 13, 2020
+
+@author: ballance
+'''
+from covsight.core.api.cover_data import CoverData
+from covsight.core.api.source_info import SourceInfo
+
+class CoverIndex(object):
+    """Reference to a coverage item within a scope.
+    
+    CoverIndex provides indexed access to coverage items (bins) within their
+    parent scope. Each cover item is identified by an integer index within
+    its scope, starting from 0.
+    
+    Coverage items are the leaf nodes in the UCIS hierarchy, representing
+    individual bins, branches, toggle states, or other coverage points.
+    Unlike scopes which form the tree structure, cover items do not have
+    children.
+    
+    A CoverIndex allows querying and modifying the coverage data (hit count)
+    and metadata (name, source location) for a specific coverage item.
+    
+    Note:
+        CoverIndex objects are typically obtained by iterating over a scope's
+        cover items or by the index returned from createNextCover(). The index
+        value is only valid within the context of its parent scope.
+        
+    Example:
+        >>> # Iterate cover items in a coverpoint
+        >>> for idx in coverpoint.coverItems():
+        ...     name = idx.getName()
+        ...     data = idx.getCoverData()
+        ...     print(f"{name}: {data.data}/{data.goal} hits")
+        ...
+        >>> # Increment a specific item's count
+        >>> idx.incrementCover(5)
+        
+    See Also:
+        Scope.coverItems(): Iterate cover items in a scope
+        Scope.createNextCover(): Create new cover item (returns index)
+        CoverData: Coverage measurement data
+        UCIS LRM Section 8.11.3 "ucis_GetCoverData"
+        UCIS LRM Section 8.11.5 "ucis_IncrementCover"
+    """
+    
+    def __init__(self):
+        super().__init__()
+        
+    def getName(self)->str:
+        """Get the name of this coverage item.
+        
+        Returns the name assigned when the cover item was created. Names
+        are optional and may be None/empty for some coverage types.
+        
+        Returns:
+            Name string, or None if no name was assigned.
+            
+        Example:
+            >>> idx = coverpoint.coverItems().__next__()
+            >>> name = idx.getName()
+            >>> print(f"Bin name: {name}")
+            
+        See Also:
+            Scope.createNextCover(): Set name when creating items
+            UCIS LRM Section 8.11.3 "ucis_GetCoverData"
+        """
+        raise NotImplementedError()
+    
+    def getCoverData(self)->CoverData:
+        """Get the coverage measurement data for this item.
+        
+        Retrieves the CoverData object containing hit count, goal, weight,
+        and other coverage metrics for this item. The returned data reflects
+        the current state and may be modified if the data structure is mutable.
+        
+        Returns:
+            CoverData object with current coverage metrics.
+            
+        Example:
+            >>> idx = coverpoint.coverItems().__next__()
+            >>> data = idx.getCoverData()
+            >>> print(f"Hits: {data.data}, Goal: {data.goal}")
+            >>> covered = (data.data >= data.goal)
+            
+        Note:
+            The returned data should be treated as a snapshot. To modify
+            coverage data, use incrementCover() or scope-level methods.
+            
+        See Also:
+            CoverData: Coverage data container
+            incrementCover(): Modify hit count
+            UCIS LRM Section 8.11.3 "ucis_GetCoverData"
+        """
+        raise NotImplementedError()
+    
+    def getSourceInfo(self)->SourceInfo:
+        """Get source location information for this coverage item.
+        
+        Returns the source file location where this coverage item was defined
+        or instantiated in the design. This links coverage results back to
+        source code.
+        
+        Returns:
+            SourceInfo object with file, line, and token information.
+            May be None if source location was not recorded.
+            
+        Example:
+            >>> idx = coverpoint.coverItems().__next__()
+            >>> src = idx.getSourceInfo()
+            >>> if src:
+            ...     print(f"Defined at {src.filename}:{src.line}")
+            
+        See Also:
+            SourceInfo: Source location data
+            FileHandle: File reference system
+            UCIS LRM Section 8.11.3 "ucis_GetCoverData"
+        """
+        raise NotImplementedError()
+    
+    def incrementCover(self, amt=1):
+        """Increment this coverage item's hit count.
+        
+        Adds the specified amount to the current hit count (data field)
+        of this coverage item. This is the primary method for recording
+        coverage events during simulation or when merging coverage databases.
+        
+        Args:
+            amt: Amount to add to hit count. Default is 1. Can be negative
+                to decrement (though unusual). Must fit in int64_t range.
+                
+        Example:
+            >>> # Record single hit
+            >>> idx.incrementCover()
+            >>>
+            >>> # Record multiple hits at once
+            >>> idx.incrementCover(10)
+            >>>
+            >>> # Verify increment
+            >>> before = idx.getCoverData().data
+            >>> idx.incrementCover(5)
+            >>> after = idx.getCoverData().data
+            >>> assert after == before + 5
+            
+        Note:
+            Some coverage items may have a limit (HAS_LIMIT flag), causing
+            counts to saturate at the limit value rather than overflow.
+            
+        See Also:
+            getCoverData(): Query current hit count
+            CoverData: Coverage data fields
+            UCIS LRM Section 8.11.5 "ucis_IncrementCover"
+        """
+        raise NotImplementedError()
+        
+        
+    

covsight/core/api/cover_instance.py

@@ -0,0 +1,79 @@
+from covsight.core.api.unimpl_error import UnimplError
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+'''
+Created on Jan 8, 2020
+
+@author: ballance
+'''
+from covsight.core.api.cvg_scope import CvgScope
+
+class CoverInstance(CvgScope):
+    """Covergroup instance scope.
+    
+    CoverInstance represents a specific instance of a covergroup when
+    per-instance coverage is enabled. It extends CvgScope to inherit
+    covergroup options (at_least, auto_bin_max, etc.).
+    
+    When a covergroup has per_instance=True, each instantiation creates
+    a COVERINSTANCE scope to track coverage separately. This enables
+    analysis of which instances are contributing to overall coverage.
+    
+    Example:
+        >>> # Covergroup with per-instance mode
+        >>> cg = design.createCovergroup("cg_bus", src_info, 1, SourceT.SV)
+        >>> cg.setPerInstance(True)
+        >>>
+        >>> # Create instances (CoverInstance objects)
+        >>> inst1 = cg.createCoverInstance("inst_0", src_info, 1, SourceT.SV)
+        >>> inst2 = cg.createCoverInstance("inst_1", src_info, 1, SourceT.SV)
+        >>>
+        >>> # Each instance has separate coverage
+        >>> for cp in inst1.coverPoints():
+        ...     data = cp.getCoverData()
+        
+    See Also:
+        CvgScope: Base class with options
+        Covergroup: Container for covergroup instances
+        Covergroup.setPerInstance(): Enable per-instance mode
+        ScopeTypeT.COVERINSTANCE: Instance scope type
+        UCIS LRM Section 6.4.3.2 "Covergroup Instances"
+    """
+    
+    def __init__(self):
+        super().__init__()
+        
+    def getStmtIndex(self):
+        """Get statement index (if applicable).
+        
+        Raises:
+            UnimplError: Not typically used for cover instances.
+        """
+        raise UnimplError()
+    
+    def setStmtIndex(self, idx):
+        """Set statement index (if applicable).
+        
+        Args:
+            idx: Statement index.
+            
+        Raises:
+            UnimplError: Not typically used for cover instances.
+        """
+        raise UnimplError()

covsight/core/api/cover_item.py

@@ -0,0 +1,99 @@
+'''
+Created on Jan 12, 2020
+
+@author: ballance
+'''
+from covsight.core.api.obj import Obj
+from covsight.core.api.unimpl_error import UnimplError
+
+class CoverItem(Obj):
+    """Base class for coverage items (bins).
+    
+    CoverItem is the base class for all coverage leaf nodes in the UCIS
+    hierarchy. Coverage items (also called "bins") represent individual
+    coverage points such as:
+    - Covergroup bins (CVGBIN)
+    - Branch outcomes (BRANCHBIN)
+    - Toggle states (TOGGLEBIN)
+    - Assertion outcomes (ASSERTBIN)
+    - FSM transitions (FSMBIN)
+    
+    Unlike scopes which form the hierarchical tree structure, coverage items
+    are leaf nodes that contain measurement data (hit counts) but no children.
+    
+    Coverage items are typically accessed via CoverIndex objects obtained by
+    iterating over a scope's cover items, rather than by direct instantiation
+    of CoverItem subclasses.
+    
+    Note:
+        This class extends Obj, inheriting the property interface for
+        accessing integer, real, string, and handle properties. Properties
+        on cover items are accessed with coverindex ≥ 0, unlike scope-level
+        properties which use coverindex = -1.
+        
+    Example:
+        >>> # Access cover items in a scope
+        >>> for cover_idx in coverpoint.coverItems():
+        ...     # Each cover_idx provides access to a CoverItem
+        ...     name = cover_idx.getName()
+        ...     data = cover_idx.getCoverData()
+        ...
+        >>> # Get property from a cover item
+        >>> count = coverpoint.getIntProperty(
+        ...     IntProperty.COUNT, coverindex=0)
+        
+    See Also:
+        CoverIndex: Reference to coverage items
+        Scope.coverItems(): Iterate cover items
+        Scope.createNextCover(): Create new cover items
+        CoverData: Coverage measurement data
+        UCIS LRM Section 8.11 "Coveritem Creation and Manipulation"
+    """
+    
+    def __init__(self):
+        super().__init__()
+        
+    def getStmtIndex(self)->int:
+        """Get the statement index for code coverage items.
+        
+        For code coverage types (statement, branch, condition, expression),
+        returns the index identifying which statement in the scope this
+        coverage item represents. This links coverage data to specific
+        statements in the source code.
+        
+        Returns:
+            Statement index (non-negative integer), or implementation-specific
+            value if not applicable for this coverage type.
+            
+        Raises:
+            UnimplError: Not implemented in base class or specific backend.
+            
+        Note:
+            This method is primarily relevant for code coverage scopes
+            (STMTBIN, BRANCHBIN, CONDBIN, EXPRBIN). For other coverage types
+            like covergroups or toggles, the return value may not be meaningful.
+            
+        See Also:
+            setStmtIndex(): Set statement index
+            CoverTypeT: Coverage type enumeration
+        """
+        raise UnimplError()
+    
+    def setStmtIndex(self, i):
+        """Set the statement index for code coverage items.
+        
+        Sets the statement index that links this coverage item to a specific
+        statement in the source code. Used primarily for code coverage types.
+        
+        Args:
+            i: Statement index (non-negative integer).
+            
+        Raises:
+            UnimplError: Not implemented in base class or specific backend.
+            
+        See Also:
+            getStmtIndex(): Query statement index
+        """
+        raise UnimplError()
+
+        

covsight/core/api/cover_type.py

@@ -0,0 +1,124 @@
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+'''
+Created on Jan 8, 2020
+
+@author: ballance
+'''
+from covsight.core.api.scope import Scope
+from covsight.core.api.unimpl_error import UnimplError
+
+class CoverType(Scope):
+    """Base class for coverage type scopes with goal/limit/weight management.
+    
+    CoverType extends Scope to add coverage-specific attributes including
+    coverage goal, limit, and weight. These attributes control how coverage
+    is measured and reported.
+    
+    - **Goal**: Target count for coverage completion
+    - **Limit**: Maximum count before saturation
+    - **Weight**: Relative importance in coverage calculations
+    
+    This class serves as a base for coverage scopes that need these attributes,
+    providing getter/setter methods that can be overridden by subclasses.
+    
+    Example:
+        >>> # CoverType is typically not used directly
+        >>> # Subclasses like Coverpoint inherit these methods
+        >>> cp = cg.createCoverpoint("cp_addr", src_info, 1, SourceT.SV)
+        >>> cp.setCoverGoal(100)
+        >>> cp.setCoverWeight(10)
+        >>> goal = cp.getCoverGoal()
+        
+    See Also:
+        Scope: Base scope class
+        Coverpoint: Subclass using goal/weight
+        CoverData: Coverage data with goal/weight fields
+    """
+    
+    def __init__(self):
+        super().__init__()
+        
+    def setCoverGoal(self, goal : int):
+        """Set the coverage goal.
+        
+        Args:
+            goal: Target count for coverage completion.
+            
+        Raises:
+            UnimplError: Not implemented in base class or specific backend.
+        """
+        raise UnimplError()
+    
+    def getCoverGoal(self)->int:
+        """Get the coverage goal.
+        
+        Returns:
+            Goal value.
+            
+        Raises:
+            UnimplError: Not implemented in base class or specific backend.
+        """
+        raise UnimplError()
+    
+    def setCoverLimit(self, limit : int):
+        """Set the coverage count limit (saturation point).
+        
+        Args:
+            limit: Maximum count value.
+            
+        Raises:
+            NotImplementedError: Not implemented in base class or specific backend.
+        """
+        raise NotImplementedError()
+    
+    def getCoverLimit(self) -> int:
+        """Get the coverage count limit.
+        
+        Returns:
+            Limit value.
+            
+        Raises:
+            NotImplementedError: Not implemented in base class or specific backend.
+        """
+        raise NotImplementedError()
+    
+    def setCoverWeight(self, weight : int):
+        """Set the coverage weight.
+        
+        Args:
+            weight: Relative weight value.
+            
+        Raises:
+            NotImplementedError: Not implemented in base class or specific backend.
+        """
+        raise NotImplementedError()
+    
+    def getCoverWeight(self) -> int:
+        """Get the coverage weight.
+        
+        Returns:
+            Weight value.
+            
+        Raises:
+            NotImplementedError: Not implemented in base class or specific backend.
+        """
+        raise NotImplementedError()
+    
+