UCIS Object-Oriented API
The UCIS object-oriented API provides access to coverage databases through a hierarchy of Python classes. This page documents every class in the public API, organized from the top of the type hierarchy down to leaf types.
Class Hierarchy
Obj
├── UCIS (Scope) ← database root; use MemFactory or SqliteUCIS
├── Scope (Obj)
│ ├── CovScope
│ │ └── FuncCovScope
│ │ └── CvgScope
│ │ ├── Covergroup
│ │ │ └── (instances returned by createCovergroup)
│ │ ├── Coverpoint
│ │ │ └── Cross
│ │ ├── CvgBinScope
│ │ ├── IgnoreBinScope
│ │ └── IllegalBinScope
│ ├── DUScope ← design unit definition
│ └── InstanceScope ← design hierarchy instance
├── HistoryNode ← test run / merge record
└── CoverItem ← bin (leaf coverage measurement)
CoverData ← data container for a bin's hit count and goal
SourceInfo ← (file, line, token) tuple
TestData ← test run metadata passed to createHistoryNode
Creating a Database
All interaction with coverage data starts by obtaining a UCIS
object from one of the backend factories.
In-Memory Backend
SQLite Backend
- class ucis.sqlite.sqlite_ucis.SqliteUCIS(db_path: str = None)
SQLite-backed UCIS database
Create or open a SQLite UCIS database
- Parameters:
db_path – Path to database file. If None, creates in-memory database.
- classmethod open_readonly(db_path: str) SqliteUCIS
Open a database in read-only mode with minimal overhead.
Skips schema validation, migration, and WAL setup. Intended for merge sources that are only read, never written.
- clone() SqliteUCIS
Return a new SqliteUCIS that is an independent copy of this database.
- getDBVersion()
Get database version
- getPathSeparator()
Get path separator
- createInstanceByName(name: str, du_name: str, fileinfo, weight: int, source, flags: int)
Create an instance scope by DU name string lookup.
- createHistoryNode(parent, logicalname: str, physicalname: str = None, kind: HistoryNodeKind = None) HistoryNode
Create a history node (test record)
- historyNodes(kind: HistoryNodeKind = None) Iterator[HistoryNode]
Iterate history nodes
- getSourceFiles()
Get list of source files
- getCoverInstances()
Get list of top-level coverage instances (scopes with no parent)
- write(file, scope=None, recurse=True, covertype=-1)
Write database (no-op for SQLite, already persistent)
- close()
Close the database
- begin_transaction()
Begin a transaction
- commit()
Commit current transaction
- rollback()
Rollback current transaction
- getIntProperty(coverindex: int, property: IntProperty) int
Get integer property with UCIS-specific handling
- merge(source_ucis, create_history: bool = True, squash_history: bool = False)
Merge coverage from another UCIS database
- Parameters:
source_ucis – Source SqliteUCIS database to merge from
create_history – Whether to create merge history node
squash_history – If True, collapse per-test history into a summary node
- Returns:
MergeStats object with statistics
- merge_many(sources, create_history: bool = True, squash_history: bool = False)
Merge multiple source databases in a single transaction.
- Parameters:
sources – Iterable of source SqliteUCIS databases to merge from
create_history – Whether to create merge history nodes
squash_history – If True, collapse per-test history into summary
- Returns:
MergeStats object with accumulated statistics
- merge_fast(source_paths, squash_history=False, workers=4)
Merge multiple source .cdb files using optimised read pattern.
Uses the first source via normal merge to establish structure, then uses fast path for remaining sources.
- Parameters:
source_paths – List of file paths to source .cdb databases.
squash_history – If True, collapse history into summary node.
workers – Number of parallel reader threads (default: 4).
- Returns:
MergeStats object with statistics.
- get_test_coverage_api()
Get test-coverage query API.
- Returns:
SqliteTestCoverage instance for querying test-coveritem associations
Example
>>> db = SqliteUCIS('coverage.cdb') >>> test_api = db.get_test_coverage_api() >>> contributions = test_api.get_all_test_contributions() >>> for info in contributions: ... print(f"{info.test_name}: {info.coverage_percent:.1f}%")
Core Classes
UCIS
The database root. Returned by MemFactory.create() and SqliteUCIS(path).
- class ucis.ucis.UCIS
Root database class for Unified Coverage Interoperability Standard.
UCIS is the top-level container for all coverage data, representing the entire coverage database. It extends Scope to act as the root of the scope hierarchy and provides database-level operations for persistence, metadata management, and history tracking.
A UCIS database can exist in two forms: - In-memory: Fast random access to all data, held in RAM - Persistent: Stored on disk in XML, SQLite, or other backend formats
Key capabilities: - Hierarchy Root: Contains top-level scopes (design units, instances) - Persistence: Read from and write to files in various formats - History Tracking: Manage test history nodes for merge tracking - Metadata: Store database version, tool info, timestamps - File Management: Create and manage file handles for source references
The database supports multiple backends (in-memory, SQLite, XML, YAML) with different trade-offs between performance, persistence, and file size.
Example
>>> # Create in-memory database >>> from ucis.mem import MemFactory >>> db = MemFactory.create() >>> >>> # Create design hierarchy >>> du = db.createScope("counter", None, 1, SourceT.SV, ... ScopeTypeT.DU_MODULE, 0) >>> inst = db.createInstance("top", None, 1, SourceT.SV, ... ScopeTypeT.INSTANCE, du, 0) >>> >>> # Save to file >>> db.write("coverage.xml") >>> db.close()
Note
UCIS objects should be created through backend-specific factory methods (MemFactory, SqliteUCIS, etc.) rather than direct instantiation.
See also
Scope: Base class for hierarchical containers HistoryNode: Test history and merge tracking UCIS LRM Section 8.1 “Database Creation and File Management” UCIS LRM Chapter 4 “Introduction to the UCIS Data Model”
- getIntProperty(coverindex: int, property: IntProperty) int
Get an integer property value from the database.
Overrides Scope.getIntProperty() to provide database-specific properties including modification status and test counts.
- Parameters:
coverindex – Index of cover item, or -1 for database-level properties.
property – Integer property identifier (IntProperty enum).
- Returns:
Integer value of the requested property.
- Raises:
UnimplError – If property is not supported.
See also
Obj.getIntProperty(): Base implementation IntProperty: Database-specific properties include IS_MODIFIED,
MODIFIED_SINCE_SIM, NUM_TESTS
- setIntProperty(coverindex: int, property: IntProperty, value: int)
Set an integer property value on the database.
Overrides Scope.setIntProperty() for database-level property handling.
- Parameters:
coverindex – Index of cover item, or -1 for database-level properties.
property – Integer property identifier (IntProperty enum).
value – New integer value for the property.
- Raises:
UnimplError – If property is not supported or read-only.
See also
Obj.setIntProperty(): Base implementation
- isModified()
Check if the database has been modified since opening.
Returns True if any changes have been made to the database since it was opened or created. This includes adding/removing scopes, modifying coverage data, or changing metadata. Read-only property.
- Returns:
Boolean indicating whether database has been modified.
- Raises:
UnimplError – If modification tracking is not supported.
Example
>>> if db.isModified(): ... print("Database has unsaved changes") ... db.write("coverage.xml")
See also
modifiedSinceSim(): Check if modified since simulation IntProperty.IS_MODIFIED: Property identifier
- modifiedSinceSim()
Check if the database has been modified since simulation.
Returns True if any changes have been made to the database after the original simulation run completed. This tracks post-simulation modifications like merging or manual edits. Read-only property.
- Returns:
Boolean indicating whether database was modified post-simulation.
- Raises:
UnimplError – If modification tracking is not supported.
See also
isModified(): Check if modified since opening IntProperty.MODIFIED_SINCE_SIM: Property identifier
- getNumTests()
Get the number of test history nodes in the database.
Returns the count of test history nodes (HistoryNodeKind.TEST) that represent individual test runs contributing to this database. This count is used for tracking test coverage and merge history. Read-only property.
- Returns:
Integer count of test history nodes (>= 0).
- Raises:
UnimplError – If test counting is not supported.
Example
>>> num = db.getNumTests() >>> print(f"Database contains coverage from {num} tests")
See also
historyNodes(): Iterate test history nodes IntProperty.NUM_TESTS: Property identifier
- getAPIVersion() str
Get the UCIS API version string.
Returns the version of the UCIS API implementation. This typically follows the UCIS standard version (e.g., “1.0”) but may include tool-specific version information.
- Returns:
String containing API version identifier.
- Raises:
UnimplError – If version information is not available.
Example
>>> version = db.getAPIVersion() >>> print(f"UCIS API version: {version}")
See also
getDBVersion(): Get database format version UCIS LRM Section 8.18.1 “ucis_GetAPIVersion”
- getWrittenBy() str
Get the tool identifier that created this database.
Returns a string identifying the tool that originally wrote/created this database. Typically includes vendor and tool name (e.g., “vendor:tool:version”).
- Returns:
String identifying the creating tool, or empty string if not set.
- Raises:
UnimplError – If tool metadata is not supported.
Example
>>> tool = db.getWrittenBy() >>> print(f"Database created by: {tool}")
See also
setWrittenBy(): Set tool identifier
- setWrittenBy(by: str)
Set the tool identifier for this database.
Stores a string identifying the tool creating or modifying this database. Convention is “vendor:tool:version” format.
- Parameters:
by – Tool identifier string (e.g., “Acme:Simulator:2.5”).
- Raises:
UnimplError – If tool metadata is not supported.
Example
>>> db.setWrittenBy("MyCompany:CoverageTool:1.0")
See also
getWrittenBy(): Retrieve tool identifier
- getWrittenTime() int
Get the timestamp when the database was written.
Returns the time (typically Unix epoch seconds) when the database was last written to persistent storage.
- Returns:
Integer timestamp (seconds since epoch), or 0 if not set.
- Raises:
UnimplError – If timestamp metadata is not supported.
Example
>>> import time >>> ts = db.getWrittenTime() >>> print(f"Written: {time.ctime(ts)}")
See also
setWrittenTime(): Set database timestamp
- setWrittenTime(time: int)
Set the timestamp for this database.
Stores the time when the database was written. Typically set automatically during write() operations.
- Parameters:
time – Timestamp as seconds since Unix epoch.
- Raises:
UnimplError – If timestamp metadata is not supported.
Example
>>> import time >>> db.setWrittenTime(int(time.time()))
See also
getWrittenTime(): Retrieve database timestamp
- getDBVersion()
Get the database format version.
Returns a version identifier for the database format/schema. This may differ from the API version if the file uses an older format.
- Returns:
Version identifier (format depends on backend).
- Raises:
UnimplError – If version information is not available.
See also
getAPIVersion(): Get API version UCIS LRM Section 8.18.2 “ucis_GetDBVersion”
- getPathSeparator()
Get the hierarchical path separator character.
Returns the character used to separate components in hierarchical scope names. Default is typically ‘/’ but can be customized per database.
- Returns:
Single character string (e.g., ‘/’, ‘.’).
- Raises:
UnimplError – If path separator is not supported.
Example
>>> sep = db.getPathSeparator() >>> path = f"top{sep}dut{sep}counter"
See also
setPathSeparator(): Change path separator UCIS LRM Section 8.1.7 “ucis_GetPathSeparator”
- setPathSeparator(separator)
Set the hierarchical path separator character.
Changes the character used for hierarchical scope name separation. This affects how full paths are constructed and interpreted.
- Parameters:
separator – Single character to use as separator (typically ‘/’ or ‘.’).
- Raises:
UnimplError – If path separator customization is not supported.
ValueError – If separator is invalid (e.g., multi-character).
Note
Changing the separator after scopes are created may cause path resolution issues. Set this before building the hierarchy.
See also
getPathSeparator(): Retrieve current separator UCIS LRM Section 8.1.8 “ucis_SetPathSeparator”
- removeScope(scope: Scope) None
Remove a scope and all its children from the database.
- Parameters:
scope – The scope to remove. Must be a direct child of this database or one of its descendant scopes.
See also
UCIS LRM Section 8.5.26 “ucis_RemoveScope”
- matchScopeByUniqueId(uid: str) Scope
Find a scope by its UNIQUE_ID string property.
- Returns:
Matching Scope, or None if not found.
See also
UCIS LRM ucis_MatchScopeByUniqueID
- matchCoverByUniqueId(uid: str)
Find a (scope, coverindex) pair by UNIQUE_ID.
- Returns:
(scope, coverindex) tuple, or (None, -1) if not found.
See also
UCIS LRM ucis_MatchCoverByUniqueID
- createInstanceByName(name: str, du_name: str, fileinfo, weight: int, source, flags: int) Scope
Create an instance scope referenced by DU name string rather than object.
Looks up the named design unit (
du_name) in the database and callscreateInstancewith the resolved scope.du_namemay be qualified ("work.counter") or unqualified ("counter").- Parameters:
name – Local instance name.
du_name – Fully- or partially-qualified DU name to look up.
fileinfo – Source location or None.
weight – Coverage weight (typically 1).
source – SourceT language constant.
flags – Scope flags (FlagsT / int bitmask).
- Returns:
Newly created instance Scope.
- Raises:
KeyError – If no DU with the given name is found.
UnimplError – If not supported by this backend.
See also
createInstance: Low-level variant taking a DU scope object UCIS LRM ucis_CreateInstanceByName
- createFileHandle(filename: str, workdir: str) FileHandle
Create a file handle for source file references.
Creates a FileHandle object representing a source file. File handles enable efficient storage of file references - each unique filename is stored once and referenced by multiple objects through handles.
- Parameters:
filename – Source file name or path. Can be absolute or relative to workdir.
workdir – Working directory for resolving relative paths. If filename is absolute, workdir is ignored. Can be None for relative-to-current.
- Returns:
FileHandle object referencing the specified file.
- Raises:
UnimplError – If file handles are not supported.
ValueError – If filename is empty or invalid.
Example
>>> # Absolute path >>> fh1 = db.createFileHandle("/project/rtl/counter.sv", None) >>> # Relative path with workdir >>> fh2 = db.createFileHandle("alu.sv", "/project/rtl") >>> # Use in source location >>> src = SourceInfo(fh2, 42, 0)
Note
The file need not exist at creation time. File handles store path information for later resolution.
See also
FileHandle: File handle operations SourceInfo: Source location using file handles UCIS LRM Section 8.12.2 “ucis_CreateFileHandle”
- createHistoryNode(parent: HistoryNode, logicalname: str, physicalname: str, kind: HistoryNodeKind) HistoryNode
Create a history node for test or merge tracking.
Creates a HistoryNode to record information about test runs, merges, or other database operations. History nodes form a tree tracking how the database was constructed over time.
- Parameters:
parent – Parent history node, or None for root-level nodes. Forms hierarchy for tracking merge operations.
logicalname – Logical identifier (e.g., test name, merge operation name).
physicalname – Physical identifier (e.g., test command, file path).
kind – Type of history node (HistoryNodeKind: TEST, TESTPLAN, MERGE, etc.).
- Returns:
Newly created HistoryNode object.
- Raises:
UnimplError – If history tracking is not supported.
ValueError – If parameters are invalid.
Example
>>> # Create test history node >>> test = db.createHistoryNode( ... None, ... "test_basic", ... "./run_sim.sh", ... HistoryNodeKind.TEST) >>> # Set test data >>> from ucis.test_data import TestData >>> from ucis.test_status_t import TestStatusT >>> td = TestData(teststatus=TestStatusT.OK, ... toolcategory="simulator", ... date="2024-01-15") >>> test.setTestData(td)
See also
HistoryNode: History node operations HistoryNodeKind: Node type enumeration TestData: Test execution metadata UCIS LRM Section 8.13.1 “ucis_CreateHistoryNode”
- historyNodes(kind: HistoryNodeKind) Iterator[HistoryNode]
Iterate over history nodes of a specific kind.
Returns an iterator over history nodes, filtered by node kind. Enables traversal of test history for analysis and reporting.
- Parameters:
kind – Type of history nodes to iterate (HistoryNodeKind enum). Use HistoryNodeKind.TEST for test runs, MERGE for merge operations.
- Yields:
HistoryNode objects matching the specified kind.
- Raises:
UnimplError – If history iteration is not supported.
Example
>>> # Iterate all test nodes >>> for test in db.historyNodes(HistoryNodeKind.TEST): ... td = test.getTestData() ... print(f"Test: {test.getLogicalName()}, Status: {td.teststatus}")
See also
getHistoryNodes(): Get history nodes as a list createHistoryNode(): Create history nodes UCIS LRM Section 8.8.1 “ucis_HistoryIterate”
- getHistoryNodes(kind: HistoryNodeKind) List[HistoryNode]
Get history nodes of a specific kind as a list.
Convenience method that returns all matching history nodes as a list rather than an iterator. Useful when you need the full collection.
- Parameters:
kind – Type of history nodes to retrieve (HistoryNodeKind enum).
- Returns:
List of HistoryNode objects matching the specified kind.
Example
>>> tests = db.getHistoryNodes(HistoryNodeKind.TEST) >>> print(f"Database contains {len(tests)} tests")
See also
historyNodes(): Iterator version
- getSourceFiles() [<class 'ucis.source_file.SourceFile'>]
Get the list of source files referenced in the database.
Returns all source files that are referenced by coverage objects through file handles. Useful for generating file-level coverage reports.
- Returns:
List of SourceFile objects representing referenced files.
- Raises:
UnimplError – If source file enumeration is not supported.
Example
>>> for src_file in db.getSourceFiles(): ... print(f"File: {src_file.getName()}")
See also
createFileHandle(): Create file references SourceFile: Source file information
- getCoverInstances() [<class 'ucis.instance_coverage.InstanceCoverage'>]
Get per-instance coverage data.
Returns coverage information organized by instance for covergroups that have per-instance coverage enabled. This allows analysis of coverage differences across multiple instances of the same module.
- Returns:
List of InstanceCoverage objects.
- Raises:
UnimplError – If instance coverage tracking is not supported.
Example
>>> for inst_cov in db.getCoverInstances(): ... print(f"Instance: {inst_cov.getInstanceName()}")
See also
InstanceCoverage: Per-instance coverage data IntProperty.CVG_PERINSTANCE: Per-instance coverage flag
- write(file: str, scope=None, recurse: bool = True, covertype: int = -1)
Write the database to a persistent file.
Serializes the coverage database to a file in the backend’s native format (XML, SQLite, YAML, etc.). This operation commits the in-memory state to persistent storage.
- Parameters:
file – Output file path. File extension may determine format (.xml, .ucis, etc.).
scope – Starting scope for partial writes. If None, writes entire database. Allows exporting subtrees of the coverage hierarchy.
recurse – If True (default), write scope and all descendants. If False, write only the specified scope level.
covertype – Coverage type mask to filter which cover items are written. Use -1 (default) for all types, or CoverTypeT mask to filter.
- Raises:
UnimplError – If write operation is not supported.
IOError – If file cannot be written.
ValueError – If parameters are invalid.
Example
>>> # Write entire database >>> db.write("coverage.xml") >>> >>> # Write subtree starting at specific scope >>> scope = db.getScopeByName("top/dut") >>> db.write("dut_coverage.xml", scope=scope) >>> >>> # Write only functional coverage (no code coverage) >>> from ucis.cover_type_t import CoverTypeT >>> db.write("funcov.xml", covertype=CoverTypeT.CVGBIN)
Note
The specific file format depends on the backend implementation. Some backends may support multiple formats based on file extension.
See also
close(): Close database and free resources UCIS LRM Section 8.1.3 “ucis_Write”
- close()
Close the database and commit changes to backing storage.
Closes the database, frees all associated resources, and (for persistent backends) ensures changes are committed to storage. After closing, the database object should not be used.
For backends with transaction support, this commits any pending transactions. For file-based backends, this may trigger an implicit write if not already saved.
- Raises:
UnimplError – If close operation is not supported.
IOError – If pending changes cannot be committed.
Example
>>> db = MemFactory.create() >>> # ... populate database ... >>> db.write("coverage.xml") >>> db.close() >>> # db should not be used after this point
Note
Best practice is to explicitly call close() when done with a database, even though Python garbage collection may eventually free resources. Use context managers (with statement) if available for automatic cleanup.
See also
write(): Save database before closing UCIS LRM Section 8.1.4 “ucis_Close”
Scope
Base class for all hierarchical containers. Every node in the design hierarchy and
the coverage model is a Scope. The key operations — creating child scopes,
iterating child scopes, and accessing cover items — are defined here.
- class ucis.scope.Scope
Base class for all UCIS scope objects.
A Scope represents a hierarchical container in the UCIS coverage model, organizing coverage data and design structure in a tree hierarchy. Scopes can contain child scopes (forming the hierarchy) and cover items (leaf-level coverage measurements).
The scope hierarchy mirrors both the design hierarchy (modules, instances, blocks, functions) and the functional coverage structure (covergroups, coverpoints, crosses). Each scope has a unique type (from ScopeTypeT) that determines its purpose and allowed operations.
Key scope capabilities: - Hierarchy Management: Create child scopes, navigate parent/child relationships - Coverage Organization: Group related cover items under scopes - Metadata Storage: Source location, weights, goals, flags - Iteration: Traverse child scopes and cover items - Property Access: Get/set scope-specific properties
Scopes form the backbone of the UCIS data model. The primary key for scope identity is the combination of (name, type) which must be unique among siblings.
Note
This is an abstract base class. Concrete implementations include InstanceScope, Covergroup, Coverpoint, and others. Use factory methods like createScope(), createInstance(), createCovergroup() to create scopes.
- type
Scope type identifier
- Type:
See also
UCIS: Root database scope UCIS LRM Section 5.1 “Scope Objects” UCIS LRM Section 8.5 “Scope Functions”
- createScope(name: str, srcinfo: SourceInfo, weight: int, source, type, flags)
Create a child scope within this scope.
Creates a new scope as a child of the current scope. The type of scope created depends on the ‘type’ parameter. Scopes form a hierarchical tree structure representing the design hierarchy or coverage organization.
The combination of (name, type) forms the primary key and must be unique among all children of this scope. Use createInstance() for INSTANCE-type scopes, as it provides additional design unit association.
- Parameters:
name – Unique local name for this scope within its parent. Must not contain path separator characters.
srcinfo – Source file location where scope is defined (file, line, column), or None if not applicable or unknown.
weight – Relative weight for coverage computation. Use 1 for normal weight, >1 for higher importance, or -1 to omit weighting.
source – HDL source language type (SourceT enum: VLOG, VHDL, SV, etc.).
type – Type of scope to create (ScopeTypeT enum: BLOCK, FUNCTION, COVERGROUP, etc.). Determines scope semantics and allowed children.
flags – Bitwise OR of scope flags (FlagsT) controlling behavior such as coverage enablement, exclusion, etc.
- Returns:
Newly created Scope object of the appropriate subclass based on type.
- Raises:
NotImplementedError – If this scope type does not support child scopes.
ValueError – If name is invalid or (name, type) combination already exists.
TypeError – If parent scope type doesn’t allow this child type.
Example
>>> # Create a function scope >>> func = parent.createScope( ... "my_function", ... SourceInfo(file_h, 42, 0), ... 1, ... SourceT.SV, ... ScopeTypeT.FUNCTION, ... 0)
Note
For INSTANCE or COVERINSTANCE scopes, use createInstance() instead, which properly associates the instance with its design unit.
See also
createInstance(): Create instance scopes with design unit association createCovergroup(): Convenience method for covergroups UCIS LRM Section 8.5.2 “ucis_CreateScope”
- createInstance(name: str, fileinfo: SourceInfo, weight: int, source: SourceT, type: ScopeTypeT, du_scope: Scope, flags: FlagsT) Scope
Create an instance scope with design unit association.
Creates a new instance scope as a child of the current scope, establishing a link to its design unit (module/entity definition). Instances represent the instantiation of a design unit within the design hierarchy.
The design unit scope (du_scope) contains the template/definition, while the instance represents a specific use. This separation enables: - Single definition, multiple instantiations - Instance-specific vs. design-unit-wide coverage - Proper hierarchical naming and navigation
- Parameters:
name – Unique local name for this instance within its parent.
fileinfo – Source location of the instantiation statement, or None.
weight – Relative weight for coverage computation (typically 1).
source – HDL source language type (SourceT.VLOG, SourceT.VHDL, etc.).
type – Must be ScopeTypeT.INSTANCE or ScopeTypeT.COVERINSTANCE.
du_scope – Reference to the design unit scope that this instance instantiates. The design unit should have a DU_* scope type (DU_MODULE, DU_ARCH, DU_PROGRAM, etc.).
flags – Bitwise OR of scope flags (FlagsT). Common flags include INST_ONCE (single instantiation) and coverage enablement flags.
- Returns:
Newly created instance Scope object.
- Raises:
NotImplementedError – If instances cannot be created under this scope.
ValueError – If name is invalid or du_scope is not a design unit.
TypeError – If type is not INSTANCE or COVERINSTANCE.
Example
>>> # Create design unit >>> du = db.createScope("adder", None, 1, SourceT.SV, ... ScopeTypeT.DU_MODULE, 0) >>> # Create instance of the design unit >>> inst = top.createInstance( ... "adder_inst", ... SourceInfo(file_h, 100, 0), ... 1, ... SourceT.SV, ... ScopeTypeT.INSTANCE, ... du, ... FlagsT.ENABLED_STMT | FlagsT.ENABLED_BRANCH)
Note
The du_scope parameter links instance to definition, enabling coverage aggregation across multiple instances of the same module.
See also
createScope(): Create non-instance scopes ScopeTypeT.DU_ANY(): Check if scope is a design unit UCIS LRM Section 8.5.7 “ucis_CreateInstance”
- createToggle(name: str, canonical_name: str, flags: FlagsT, toggle_metric: ToggleMetricT, toggle_type: ToggleTypeT, toggle_dir: ToggleDirT) Scope
Create a toggle coverage scope for signal transition tracking.
Creates a toggle coverage scope to track signal transitions (0->1, 1->0). Toggle coverage measures whether signals change value during simulation, detecting stuck-at faults and exercising signal paths.
- Parameters:
name – Local name for the toggle scope (signal identifier).
canonical_name – Fully qualified hierarchical name of the signal.
flags – Bitwise OR of scope flags (FlagsT.ENABLED_TOGGLE typically set).
toggle_metric – Toggle metric type (ToggleMetricT) specifying what transitions are measured (single-bit, vector, etc.).
toggle_type – Toggle type (ToggleTypeT) indicating signal category (register, net, port, etc.).
toggle_dir – Toggle direction (ToggleDirT) specifying which transitions are tracked (UP: 0->1, DOWN: 1->0, BOTH, INTERNAL).
- Returns:
Newly created toggle Scope object.
- Raises:
NotImplementedError – If toggle coverage is not supported.
ValueError – If parameters are invalid or incompatible.
Example
>>> # Create toggle coverage for a signal >>> toggle = scope.createToggle( ... "data_valid", ... "/top/dut/data_valid", ... FlagsT.ENABLED_TOGGLE, ... ToggleMetricT.SCALAR, ... ToggleTypeT.REG, ... ToggleDirT.BOTH)
Note
Toggle coverage is typically generated automatically by coverage tools. This method is used when constructing or modifying databases.
See also
ToggleMetricT: Toggle measurement types ToggleTypeT: Signal type classification ToggleDirT: Transition direction UCIS LRM Section 6.4 “Toggle Coverage”
- createCovergroup(name: str, srcinfo: SourceInfo, weight: int, source) Covergroup
Create a SystemVerilog covergroup scope.
Convenience method to create a covergroup scope for functional coverage. Covergroups contain coverpoints and crosses that define coverage bins for tracking design stimulus and state space.
This method creates a scope with type COVERGROUP or COVERINSTANCE depending on context. Covergroups can be defined at design unit level (type) or instance level (per-instance coverage).
- Parameters:
name – Unique name for the covergroup within its parent.
srcinfo – Source location where covergroup is declared (file, line, column), or None if not available.
weight – Relative weight for coverage computation (typically 1).
source – HDL source language, typically SourceT.SV (SystemVerilog).
- Returns:
Newly created Covergroup scope object.
- Raises:
NotImplementedError – If covergroups cannot be created in this context.
ValueError – If name is invalid or already exists.
Example
>>> # Create a covergroup >>> cg = instance.createCovergroup( ... "addr_cg", ... SourceInfo(file_h, 50, 0), ... 1, ... SourceT.SV) >>> # Add coverpoints to the covergroup >>> cp = cg.createCoverpoint("addr", src_info, 1, SourceT.SV)
Note
Use Covergroup.setPerInstance() to control whether coverage is collected per-instance or aggregated at design unit level.
See also
Covergroup: Covergroup-specific operations Coverpoint: Coverpoint creation within covergroups UCIS LRM Section 6.3 “Functional Coverage”
- createNextCover(name: str, data: CoverData, sourceinfo: SourceInfo) CoverIndex
Create a coverage bin (cover item) within this scope.
Adds a new cover item (bin) to this scope’s collection of coverage measurements. Cover items are leaf nodes that track actual coverage data such as hit counts, goals, and weights.
The cover item type is determined by the scope type: - COVERPOINT scope: Creates CVGBIN cover items - BRANCH scope: Creates BRANCHBIN cover items - TOGGLE scope: Creates TOGGLEBIN cover items - etc.
- Parameters:
name – Name for this cover item (e.g., bin name, branch ID).
data – Coverage data including goal, weight, hit count (data), and limit. The CoverData object encapsulates all measurement values.
sourceinfo – Source location associated with this cover item, or None. For code coverage, this is typically the line being measured.
- Returns:
CoverIndex reference to the newly created cover item. The index can be used with property methods to access/modify cover item data.
- Raises:
NotImplementedError – If this scope type doesn’t support cover items.
ValueError – If name is invalid or data is inconsistent.
Example
>>> # Create a coverpoint bin >>> data = CoverData(goal=1, weight=1, data=0, limit=1) >>> idx = coverpoint.createNextCover( ... "bin_low", ... data, ... SourceInfo(file_h, 60, 0)) >>> # Later, increment the bin >>> coverpoint.setIntProperty(idx, IntProperty.COVER_DATA, 5)
Note
The term “NextCover” indicates appending to the cover item collection. Cover items are indexed sequentially starting from 0.
See also
CoverData: Coverage data structure CoverIndex: Cover item reference UCIS LRM Section 8.11.1 “ucis_CreateNextCover”
- createNextTransition(from_state_name: str, to_state_name: str, data: CoverData = None, srcinfo: SourceInfo = None) CoverIndex
Create an FSM transition cover item between two named states.
This is the standard API for creating FSM transitions, analogous to ucis_CreateNextTransition in the UCIS C API. If the named states do not yet exist in this FSM scope they are created automatically.
- Parameters:
from_state_name – Name of the source state.
to_state_name – Name of the destination state.
data – Initial CoverData (FSMBIN type), or None.
srcinfo – Source location, or None.
- Returns:
CoverIndex for the new transition cover item.
- Raises:
UnimplError – If the scope type does not support FSM transitions.
See also
UCIS LRM ucis_CreateNextTransition
- removeCover(coverindex: int) None
Remove a cover item from this scope by index.
- Parameters:
coverindex – Zero-based index of the cover item to remove.
See also
UCIS LRM Section 8.11.3 “ucis_RemoveCover”
- getWeight()
Get the weight of this scope.
Retrieves the relative weight used in coverage computation. Weights determine the contribution of this scope to parent scope coverage percentages. Higher weights make this scope more important.
- Returns:
Integer weight value. Typically 1 for normal importance, >1 for higher importance, or -1 if weight is not applicable.
- Raises:
NotImplementedError – If weight is not supported for this scope type.
See also
setWeight(): Modify scope weight IntProperty.SCOPE_WEIGHT: Weight property identifier
- setWeight(w)
Set the weight of this scope.
Modifies the relative weight used in coverage computation. This affects how much this scope contributes to its parent’s coverage percentage.
- Parameters:
w – New weight value. Use 1 for normal importance, >1 for higher importance, or -1 to indicate no weight.
- Raises:
NotImplementedError – If weight is not supported for this scope type.
ValueError – If weight value is invalid.
See also
getWeight(): Retrieve current weight
- getGoal() int
Get the coverage goal for this scope.
Retrieves the target coverage percentage (0-100) for this scope. Goals define the threshold for considering coverage “complete”.
- Returns:
Integer coverage goal as a percentage (0-100). Default is typically 100.
- Raises:
NotImplementedError – If goals are not supported for this scope type.
Example
>>> goal = scope.getGoal() >>> if goal == 100: ... print("Full coverage required")
See also
setGoal(): Modify coverage goal IntProperty.SCOPE_GOAL: Goal property identifier
- setGoal(goal) int
Set the coverage goal for this scope.
Modifies the target coverage percentage (0-100) for this scope. Setting a goal below 100 indicates that partial coverage is acceptable.
- Parameters:
goal – Target coverage percentage (0-100).
- Returns:
The goal value that was set.
- Raises:
NotImplementedError – If goals are not supported for this scope type.
ValueError – If goal is not in range 0-100.
Example
>>> scope.setGoal(95) # 95% coverage is sufficient
See also
getGoal(): Retrieve current goal
- getFlags() FlagsT
Get the flags for this scope.
Retrieves the bitwise flags that control scope behavior. Flags indicate enablement of coverage types, exclusion status, and other properties.
- Returns:
FlagsT bitwise flags. Test individual flags using bitwise AND.
- Raises:
NotImplementedError – If flags are not supported for this scope type.
Example
>>> flags = scope.getFlags() >>> if flags & FlagsT.ENABLED_STMT: ... print("Statement coverage enabled") >>> if flags & FlagsT.SCOPE_EXCLUDED: ... print("Scope is excluded from coverage")
See also
FlagsT: Flag definitions UCIS LRM Section 8.5.21 “ucis_GetScopeFlags”
- getScopeType() ScopeTypeT
Get the type of this scope.
Retrieves the scope type which determines the scope’s semantics and allowed operations. The type is one of the ScopeTypeT enum values.
- Returns:
ScopeTypeT enum value indicating scope type (INSTANCE, COVERGROUP, FUNCTION, TOGGLE, etc.).
- Raises:
NotImplementedError – If scope type cannot be determined.
Example
>>> scope_type = scope.getScopeType() >>> if scope_type == ScopeTypeT.COVERGROUP: ... print("This is a covergroup") >>> if ScopeTypeT.DU_ANY(scope_type): ... print("This is a design unit")
See also
ScopeTypeT: Scope type enumeration UCIS LRM Section 8.5.24 “ucis_GetScopeType”
- getScopeName() str
Get the local name of this scope.
Retrieves the local name (not the full hierarchical path) of this scope. The name is unique among siblings with the same type.
- Returns:
String local name of the scope.
- Raises:
NotImplementedError – If name cannot be retrieved.
Example
>>> name = scope.getScopeName() >>> print(f"Scope name: {name}")
Note
To get the full hierarchical path, use the path separator and traverse parents, or use database path methods if available.
See also
UCIS LRM Section 8.5.27 “ucis_GetScopeName”
- getSourceInfo() SourceInfo
Get the source location information for this scope.
Retrieves the source file, line number, and column where this scope is defined in the HDL source code.
- Returns:
SourceInfo object containing file handle, line, and column, or None if source location is not available.
- Raises:
NotImplementedError – If source info is not supported.
Example
>>> src = scope.getSourceInfo() >>> if src: ... print(f"Defined at line {src.line}")
See also
SourceInfo: Source location data structure UCIS LRM Section 8.5.23 “ucis_GetScopeSourceInfo”
- scopes(mask: ScopeTypeT) Iterator[Scope]
Iterate over child scopes of this scope.
Returns an iterator over immediate child scopes, optionally filtered by scope type. This enables hierarchical traversal of the scope tree.
- Parameters:
mask – Scope type mask (ScopeTypeT) to filter results. Only scopes whose type matches the mask are returned. Use ScopeTypeT.ALL to iterate all children.
- Yields:
Scope objects that are children of this scope and match the type mask.
- Raises:
NotImplementedError – If iteration is not supported.
Example
>>> # Iterate all child scopes >>> for child in scope.scopes(ScopeTypeT.ALL): ... print(f"Child: {child.getScopeName()}") >>> >>> # Iterate only covergroups >>> for cg in scope.scopes(ScopeTypeT.COVERGROUP): ... print(f"Covergroup: {cg.getScopeName()}")
See also
coverItems(): Iterate cover items within this scope UCIS LRM Section 8.6.1 “ucis_ScopeIterate”
- coverItems(mask: CoverTypeT) Iterator[CoverIndex]
Iterate over cover items (bins) in this scope.
Returns an iterator over cover items contained in this scope, optionally filtered by coverage type. Cover items are the leaf-level measurements.
- Parameters:
mask – Coverage type mask (CoverTypeT) to filter results. Only cover items whose type matches the mask are returned. Use appropriate mask for the scope type (e.g., CoverTypeT.CVGBIN for coverpoints).
- Yields:
CoverIndex references to cover items in this scope that match the type mask. Use the index with property methods to access cover data.
- Raises:
NotImplementedError – If cover item iteration is not supported.
Example
>>> # Iterate all bins in a coverpoint >>> for idx in coverpoint.coverItems(CoverTypeT.CVGBIN): ... name = coverpoint.getStringProperty(idx, StrProperty.NAME) ... count = coverpoint.getIntProperty(idx, IntProperty.COVER_DATA) ... print(f"Bin {name}: {count} hits")
See also
scopes(): Iterate child scopes createNextCover(): Create cover items UCIS LRM Section 8.7.1 “ucis_CoverIterate”
- getIntProperty(coverindex: int, property: IntProperty) int
Get an integer property value from this scope or a cover item.
Overrides Obj.getIntProperty() to provide scope-specific property handling. Automatically maps SCOPE_GOAL to the goal accessor method for convenience.
- Parameters:
coverindex – Index of cover item, or -1 for scope-level properties.
property – Integer property identifier (IntProperty enum).
- Returns:
Integer value of the requested property.
- Raises:
NotImplementedError – If property is not supported.
Example
>>> # Get scope goal using property interface >>> goal = scope.getIntProperty(-1, IntProperty.SCOPE_GOAL) >>> # Get weight of first cover item >>> weight = scope.getIntProperty(0, IntProperty.COVER_WEIGHT)
See also
Obj.getIntProperty(): Base implementation getGoal(): Direct goal accessor
- setIntProperty(coverindex: int, property: IntProperty, value: int)
Set an integer property value on this scope or a cover item.
Overrides Obj.setIntProperty() to provide scope-specific property handling. Automatically maps SCOPE_GOAL to the goal mutator method for convenience.
- Parameters:
coverindex – Index of cover item, or -1 for scope-level properties.
property – Integer property identifier (IntProperty enum).
value – New integer value for the property.
- Raises:
NotImplementedError – If property is not supported or read-only.
Example
>>> # Set scope goal using property interface >>> scope.setIntProperty(-1, IntProperty.SCOPE_GOAL, 95) >>> # Set weight of first cover item >>> scope.setIntProperty(0, IntProperty.COVER_WEIGHT, 10)
See also
Obj.setIntProperty(): Base implementation setGoal(): Direct goal mutator
HistoryNode
Records one test run or merge operation in the database’s provenance tree.
Create via createHistoryNode(); iterate via
historyNodes().
- class ucis.history_node.HistoryNode
History node tracking test runs and merge operations.
HistoryNode represents a node in the coverage database history tree. History nodes track the provenance of coverage data, recording: - Individual test runs (TEST nodes) with complete execution metadata - Database merge operations (MERGE nodes) combining multiple sources
The history tree enables: - Traceability of which tests contributed to coverage - Regression analysis and test filtering - Coverage attribution and debugging - Merge tracking for database composition
Each TEST history node contains comprehensive test metadata including execution status, timing, command line, seed, user, and resource usage.
History nodes extend Obj, so they support the property interface for additional metadata storage.
Example
>>> from ucis.test_status_t import TestStatusT >>> from ucis.test_data import TestData >>> >>> # Create test history node >>> test = db.createHistoryNode( ... parent=None, ... logicalName="test_basic", ... physicalName="/results/test_basic.ucis", ... kind=HistoryNodeKind.TEST) >>> >>> # Set test metadata >>> test_data = TestData( ... teststatus=TestStatusT.OK, ... toolcategory="simulator", ... date="2024-01-15", ... seed="12345") >>> test.setTestData(test_data) >>> >>> # Query test info >>> status = test.getTestStatus() >>> seed = test.getSeed() >>> cmd = test.getCmd()
See also
UCIS.createHistoryNode(): Create history nodes HistoryNodeKind: Node type enumeration TestStatusT: Test status values TestData: Test metadata container UCIS LRM Section 4.13 “History Nodes” UCIS LRM Section 8.13 “History Node Management”
- setTestData(testdata: TestData)
Set test metadata from TestData object.
Convenience method to set all test-related fields from a TestData object in one call. Calls individual setters for each field.
- Parameters:
testdata – TestData object containing test metadata.
Example
>>> test_data = TestData( ... teststatus=TestStatusT.OK, ... toolcategory="simulator", ... date="2024-01-15", ... seed="12345") >>> hist_node.setTestData(test_data)
See also
TestData: Test metadata container
- getUserAttr()
- getParent()
- getKind() HistoryNodeKind
- getTestStatus() TestStatusT
- setTestStatus(status: TestStatusT)
- getArgs() [<class 'str'>]
- setArgs(args: [<class 'str'>])
- getCompulsory() [<class 'str'>]
- setCompulsory(compulsory: [<class 'str'>])
- getComment()
- setComment(comment)
Coverage Scope Hierarchy
CovScope
Base class for generic coverage scopes (code coverage types such as branch and
toggle). Extends Scope.
- class ucis.cov_scope.CovScope
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
FuncCovScope
Base class for functional coverage scopes. Extends CovScope.
- class ucis.func_cov_scope.FuncCovScope
Base class for functional coverage scopes.
FuncCovScope serves as the base class for all functional coverage scope types including covergroups, coverpoints, and crosses. It extends CovScope to provide functional coverage-specific behaviors.
Functional coverage scopes measure design functionality by tracking how well test stimulus exercises specified design features, as opposed to code coverage which measures structural code execution.
This class is primarily a marker class in the hierarchy. Concrete functionality is provided by subclasses: - CvgScope: Coverpoint and cross options - Covergroup: Container for coverpoints and crosses - Coverpoint: Individual coverage variable - Cross: Cross-product coverage
Example
>>> # FuncCovScope is not directly instantiated >>> # Use concrete subclasses instead: >>> cg = design.createCovergroup("cg_bus", src_info, 1, SourceT.SV) >>> cp = cg.createCoverpoint("cp_addr", src_info, 1, SourceT.SV)
See also
CovScope: Base coverage scope class CvgScope: Coverage scope with options Covergroup: Covergroup container Coverpoint: Coverpoint with bins UCIS LRM Section 6.4.3 “Functional Coverage”
CvgScope
Base class for covergroup-level scopes (groups, coverpoints, crosses).
Provides shared attributes such as at_least, auto_bin_max, and
comment. Extends FuncCovScope.
- class ucis.cvg_scope.CvgScope
Base class for coverage group scopes (coverpoints and crosses).
CvgScope provides common options and behaviors for functional coverage scopes including coverpoints and crosses. It defines the configuration options that control how bins are created and how coverage is measured.
CvgScope extends FuncCovScope and adds options specific to SystemVerilog covergroup semantics: - at_least: Minimum hit count for a bin to be considered covered - auto_bin_max: Maximum number of automatically generated bins - detect_overlap: Whether to detect overlapping bin ranges - strobe: Whether to use strobe sampling - comment: Descriptive comment text
These options typically mirror SystemVerilog covergroup/coverpoint options and affect how coverage tools process the coverage data.
- Subclasses:
Coverpoint: Individual coverage variable with bins
Cross: Cross-product coverage of multiple coverpoints
Covergroup: Container for coverpoints and crosses (via inheritance)
Example
>>> # Configure coverpoint options >>> cp.setAtLeast(10) # Each bin needs 10+ hits >>> cp.setAutoBinMax(64) # Max 64 auto-generated bins >>> cp.setDetectOverlap(True) # Warn on overlapping bins >>> cp.setComment("Address bus coverage") >>> >>> # Query options >>> threshold = cp.getAtLeast() >>> print(f"Coverage threshold: {threshold}")
See also
Coverpoint: Coverpoint with bins Cross: Cross-product coverage Covergroup: Covergroup container FuncCovScope: Base functional coverage class UCIS LRM Section 6.4.3 “Functional Coverage”
- getAtLeast() int
Get the minimum hit count for bins to be considered covered.
Returns the at_least threshold, which specifies how many times a bin must be hit before it counts as covered. This is the default goal for all bins in this scope unless overridden per-bin.
- Returns:
Minimum hit count threshold (typically 1 or more).
Example
>>> threshold = cp.getAtLeast() >>> print(f"Bins need {threshold}+ hits to be covered")
See also
setAtLeast(): Set the threshold IntProperty.CVG_ATLEAST: Underlying property
- setAtLeast(atleast)
Set the minimum hit count for bins to be considered covered.
Sets the at_least threshold for all bins in this scope. Bins with hit counts below this threshold are not considered covered.
- Parameters:
atleast – Minimum hit count (typically 1 or more). Use 1 for “hit at least once” semantics.
Example
>>> # Standard: bins need 1+ hits >>> cp.setAtLeast(1) >>> >>> # Require multiple hits for confidence >>> cp.setAtLeast(10)
See also
getAtLeast(): Query current threshold
- getAutoBinMax() int
Get the maximum number of automatically generated bins.
Returns the limit on how many bins can be automatically generated for this scope. Applies to auto-generated bins when explicit bins are not specified.
- Returns:
Maximum number of auto bins (e.g., 64, 128).
Example
>>> max_bins = cp.getAutoBinMax() >>> print(f"Auto-bin limit: {max_bins}")
See also
setAutoBinMax(): Set the limit IntProperty.CVG_AUTOBINMAX: Underlying property
- setAutoBinMax(auto_max)
Set the maximum number of automatically generated bins.
Sets the limit on automatic bin generation. When a coverpoint uses auto bins, this controls how many bins are created.
- Parameters:
auto_max – Maximum number of auto bins (e.g., 64, 128).
Example
>>> # Allow up to 64 auto bins >>> cp.setAutoBinMax(64) >>> >>> # Increase limit for wide value ranges >>> cp.setAutoBinMax(256)
See also
getAutoBinMax(): Query current limit
- getDetectOverlap() bool
Query whether overlapping bin detection is enabled.
Returns whether the tool should detect and warn about overlapping bin ranges in this scope. Overlapping bins can lead to double-counting.
- Returns:
True if overlap detection is enabled, False otherwise.
Example
>>> if cp.getDetectOverlap(): ... print("Overlap detection enabled")
See also
setDetectOverlap(): Enable/disable overlap detection IntProperty.CVG_DETECTOVERLAP: Underlying property
- setDetectOverlap(detect: bool)
Enable or disable overlapping bin detection.
Controls whether the tool should detect and warn about overlapping bin ranges. Useful for catching bin definition errors.
- Parameters:
detect – True to enable overlap detection, False to disable.
Example
>>> # Enable overlap checking >>> cp.setDetectOverlap(True)
See also
getDetectOverlap(): Query current setting
- getStrobe() bool
Query whether strobe sampling is enabled.
Returns whether this scope uses strobe (end-of-timestep) sampling instead of immediate sampling.
- Returns:
True if strobe sampling is enabled, False for immediate sampling.
Example
>>> if cp.getStrobe(): ... print("Using strobe sampling")
See also
setStrobe(): Configure sampling mode IntProperty.CVG_STROBE: Underlying property
- setStrobe(s: bool)
Enable or disable strobe sampling.
Controls whether sampling occurs immediately or at end-of-timestep (strobe). Strobe sampling can avoid race conditions.
- Parameters:
s – True for strobe (end-of-timestep) sampling, False for immediate.
Example
>>> # Use strobe sampling to avoid races >>> cp.setStrobe(True)
See also
getStrobe(): Query sampling mode
- getComment() str
Get the comment text for this scope.
Returns descriptive comment text associated with this coverage scope.
- Returns:
Comment string, or empty string if none.
Example
>>> comment = cp.getComment() >>> print(f"Description: {comment}")
See also
setComment(): Set comment text StrProperty.COMMENT: Underlying property
- setComment(c: str)
Set the comment text for this scope.
Associates descriptive comment text with this coverage scope for documentation purposes.
- Parameters:
c – Comment string (can be empty).
Example
>>> cp.setComment("Measures address bus values")
See also
getComment(): Query comment text
- getIntProperty(coverindex: int, property: IntProperty) int
Get an integer property value from this scope or a cover item.
Overrides Obj.getIntProperty() to provide scope-specific property handling. Automatically maps SCOPE_GOAL to the goal accessor method for convenience.
- Parameters:
coverindex – Index of cover item, or -1 for scope-level properties.
property – Integer property identifier (IntProperty enum).
- Returns:
Integer value of the requested property.
- Raises:
NotImplementedError – If property is not supported.
Example
>>> # Get scope goal using property interface >>> goal = scope.getIntProperty(-1, IntProperty.SCOPE_GOAL) >>> # Get weight of first cover item >>> weight = scope.getIntProperty(0, IntProperty.COVER_WEIGHT)
See also
Obj.getIntProperty(): Base implementation getGoal(): Direct goal accessor
- setIntProperty(coverindex: int, property: IntProperty, value: int)
Set an integer property value on this scope or a cover item.
Overrides Obj.setIntProperty() to provide scope-specific property handling. Automatically maps SCOPE_GOAL to the goal mutator method for convenience.
- Parameters:
coverindex – Index of cover item, or -1 for scope-level properties.
property – Integer property identifier (IntProperty enum).
value – New integer value for the property.
- Raises:
NotImplementedError – If property is not supported or read-only.
Example
>>> # Set scope goal using property interface >>> scope.setIntProperty(-1, IntProperty.SCOPE_GOAL, 95) >>> # Set weight of first cover item >>> scope.setIntProperty(0, IntProperty.COVER_WEIGHT, 10)
See also
Obj.setIntProperty(): Base implementation setGoal(): Direct goal mutator
- getStringProperty(coverindex: int, property: StrProperty) str
Get a string property value from this object.
Retrieves string-valued properties such as names, comments, file paths, and other textual attributes.
- Parameters:
coverindex – Index of cover item within parent scope. Use -1 to apply the property to the scope itself rather than a specific cover item.
property – String property identifier from the StrProperty enumeration, such as NAME, COMMENT, FILE_NAME, etc.
- Returns:
The string value of the requested property.
- Raises:
UnimplError – If the property is not implemented for this object type.
ValueError – If the property is not applicable to this object type.
Example
>>> # Get the name of a scope >>> name = scope.getStringProperty(-1, StrProperty.NAME) >>> # Get a comment on a cover item >>> comment = scope.getStringProperty(0, StrProperty.COMMENT)
See also
setStringProperty(): Set string property values UCIS LRM Section 8.3.9 “ucis_GetStringProperty”
- setStringProperty(coverindex: int, property: StrProperty, value: str)
Set a string property value on this object.
Modifies string-valued properties such as names, comments, and other textual attributes.
- Parameters:
coverindex – Index of cover item within parent scope. Use -1 to apply the property to the scope itself rather than a specific cover item.
property – String property identifier from the StrProperty enumeration, such as NAME, COMMENT, etc.
value – New string value for the property.
- Raises:
UnimplError – If the property is not implemented for this object type.
ValueError – If the property is not applicable or read-only.
Example
>>> # Set a comment on a scope >>> scope.setStringProperty(-1, StrProperty.COMMENT, "Main test scope") >>> # Set a comment on a specific cover item >>> scope.setStringProperty(0, StrProperty.COMMENT, "Edge case")
Note
Some string properties like NAME may be read-only after object creation to maintain data model consistency.
See also
getStringProperty(): Get string property values UCIS LRM Section 8.3.10 “ucis_SetStringProperty”
Covergroup
A SystemVerilog or SystemC covergroup type definition. Contains
Coverpoint, Cross, and
per-instance coverage children.
Create via createCovergroup().
- class ucis.covergroup.Covergroup
SystemVerilog/SystemC covergroup for functional coverage.
Covergroup represents a SystemVerilog/SystemC/e covergroup, which is a collection of coverpoints and crosses that measure functional coverage. Covergroups can be defined at the module/class level or instantiated multiple times within a design.
A covergroup contains: - Coverpoints: Individual coverage variables with bins - Crosses: Cross-product coverage of multiple coverpoints - Options: Configuration like per-instance mode, merge behavior
Covergroups support two modes: 1. Type-level: Single coverage for all instances (merge_instances=True) 2. Per-instance: Separate coverage per instance (per_instance=True)
The scope type is COVERGROUP for covergroup types or COVERINSTANCE for covergroup instances.
- Inherited from CvgScope
at_least, auto_bin_max, detect_overlap, strobe, comment
Example
>>> # Create covergroup type >>> cg = design.createCovergroup("cg_bus_transaction", src_info, ... weight=10, source=SourceT.SV) >>> cg.setPerInstance(False) # Type-level coverage >>> cg.setMergeInstances(True) # Merge across instances >>> >>> # Add coverpoint for address >>> cp = cg.createCoverpoint("cp_addr", src_info, weight=1, ... source=SourceT.SV) >>> >>> # Add cross coverage >>> cross = cg.createCross("addr_x_data", src_info, weight=1, ... source=SourceT.SV, points_l=[cp_addr, cp_data])
See also
CvgScope: Base class for coverage scopes Coverpoint: Individual coverage variable Cross: Cross-product coverage ScopeTypeT.COVERGROUP: Scope type for covergroup types ScopeTypeT.COVERINSTANCE: Scope type for covergroup instances UCIS LRM Section 6.4.3.1 “UCIS_COVERGROUP”
- getPerInstance() bool
Query whether this covergroup collects per-instance coverage.
Returns whether coverage is collected separately for each instance of this covergroup (per-instance mode) or merged across all instances (type-level mode).
- Returns:
True if per-instance coverage is enabled, False for type-level.
Example
>>> if cg.getPerInstance(): ... print("Per-instance coverage enabled") ... else: ... print("Type-level coverage (merged)")
See also
setPerInstance(): Configure per-instance mode IntProperty.CVG_PERINSTANCE: Underlying property
- setPerInstance(perinst)
Configure whether this covergroup collects per-instance coverage.
Sets whether coverage should be collected separately for each instance of this covergroup. In per-instance mode, each instantiation gets its own coverage data. In type-level mode (default), coverage from all instances is merged.
- Parameters:
perinst – True for per-instance coverage, False for type-level.
Example
>>> # Type-level coverage (merge all instances) >>> cg.setPerInstance(False) >>> cg.setMergeInstances(True) >>> >>> # Per-instance coverage (track separately) >>> cg.setPerInstance(True) >>> cg.setMergeInstances(False)
See also
getPerInstance(): Query per-instance mode setMergeInstances(): Control instance merging
- getGetInstCoverage() bool
Query whether instance coverage should be retrieved.
Returns whether the tool should retrieve coverage from individual instances when collecting coverage data.
- Returns:
True if instance coverage retrieval is enabled, False otherwise.
See also
setGetInstCoverage(): Configure instance coverage retrieval
- setGetInstCoverage(s: bool)
Configure whether instance coverage should be retrieved.
Sets whether the tool should retrieve coverage from individual instances when collecting coverage data.
- Parameters:
s – True to enable instance coverage retrieval, False to disable.
See also
getGetInstCoverage(): Query setting
- getMergeInstances() bool
Query whether coverage from multiple instances should be merged.
Returns whether coverage data from multiple instantiations of this covergroup should be merged together (type-level) or kept separate (per-instance).
- Returns:
True if instances are merged, False if kept separate.
Example
>>> if cg.getMergeInstances(): ... print("Coverage merged across instances")
See also
setMergeInstances(): Configure merging behavior IntProperty.CVG_MERGEINSTANCES: Underlying property
- setMergeInstances(m: bool)
Configure whether coverage from multiple instances should be merged.
Sets whether coverage data from multiple instantiations of this covergroup should be merged together. When True (default), all instances contribute to a single set of coverage data. When False, each instance maintains separate coverage.
- Parameters:
m – True to merge instances (type-level), False to keep separate.
Example
>>> # Type-level: merge all instances >>> cg.setMergeInstances(True) >>> cg.setPerInstance(False) >>> >>> # Per-instance: keep separate >>> cg.setMergeInstances(False) >>> cg.setPerInstance(True)
See also
getMergeInstances(): Query merge setting setPerInstance(): Configure per-instance mode
- createCoverpoint(name: str, srcinfo: SourceInfo, weight: int, source) CoverType
Create a coverpoint within this covergroup.
Creates a new coverpoint (coverage variable with bins) as a child of this covergroup. The coverpoint will measure coverage of a single variable or expression.
- Parameters:
name – Coverpoint name (e.g., “cp_addr”, “my_coverpoint”).
srcinfo – Source location where coverpoint is defined.
weight – Relative weight for coverage calculations. Use -1 for no weight.
source – Source language (e.g., SourceT.SV for SystemVerilog).
- Returns:
Newly created Coverpoint object.
Example
>>> cp_addr = cg.createCoverpoint("cp_addr", src_info, ... weight=1, source=SourceT.SV) >>> # Add bins to coverpoint >>> cp_addr.createBin("low", src_info, at_least=1, count=0, ... rhs="[0:255]")
See also
Coverpoint: Coverpoint class createCross(): Create cross coverage UCIS LRM Section 6.4.3.3 “UCIS_COVERPOINT”
- createCross(name: str, srcinfo: SourceInfo, weight: int, source: SourceT, points_l: List[Coverpoint]) CoverType
Create a cross (cross-product coverage) within this covergroup.
Creates a new cross that measures cross-product coverage of multiple coverpoints. A cross automatically generates bins for combinations of the crossed coverpoint bins.
- Parameters:
name – Cross name (e.g., “addr_x_data”, “mode_cross”).
srcinfo – Source location where cross is defined.
weight – Relative weight for coverage calculations. Use -1 for no weight.
source – Source language (e.g., SourceT.SV for SystemVerilog).
points_l – List of Coverpoint objects to cross.
- Returns:
Newly created Cross object.
Example
>>> # Create two coverpoints >>> cp_addr = cg.createCoverpoint("cp_addr", src_info, 1, SourceT.SV) >>> cp_data = cg.createCoverpoint("cp_data", src_info, 1, SourceT.SV) >>> >>> # Create cross of the two coverpoints >>> cross = cg.createCross("addr_x_data", src_info, weight=2, ... source=SourceT.SV, ... points_l=[cp_addr, cp_data])
See also
Cross: Cross coverage class createCoverpoint(): Create individual coverpoint UCIS LRM Section 6.4.3.4 “UCIS_CROSS”
- createCoverInstance(name: str, srcinfo: SourceInfo, weight: int, source) Covergroup
Create a covergroup instance under this covergroup type.
Creates a new COVERINSTANCE scope representing a specific instantiation of this covergroup type. Used when per-instance coverage is enabled to track coverage separately for each instance.
- Parameters:
name – Instance name identifying this instantiation.
srcinfo – Source location of the instance.
weight – Relative weight for this instance.
source – Source language.
- Returns:
Newly created Covergroup object representing the instance.
Example
>>> # Covergroup type (per-instance enabled) >>> cg_type = module.createCovergroup("cg_transaction", src_info, ... weight=10, source=SourceT.SV) >>> cg_type.setPerInstance(True) >>> >>> # Create instances >>> inst1 = cg_type.createCoverInstance("inst_0", src_info, 1, SourceT.SV) >>> inst2 = cg_type.createCoverInstance("inst_1", src_info, 1, SourceT.SV)
See also
setPerInstance(): Enable per-instance coverage ScopeTypeT.COVERINSTANCE: Instance scope type
- getIntProperty(coverindex: int, property: IntProperty) int
Get an integer property value from this scope or a cover item.
Overrides Obj.getIntProperty() to provide scope-specific property handling. Automatically maps SCOPE_GOAL to the goal accessor method for convenience.
- Parameters:
coverindex – Index of cover item, or -1 for scope-level properties.
property – Integer property identifier (IntProperty enum).
- Returns:
Integer value of the requested property.
- Raises:
NotImplementedError – If property is not supported.
Example
>>> # Get scope goal using property interface >>> goal = scope.getIntProperty(-1, IntProperty.SCOPE_GOAL) >>> # Get weight of first cover item >>> weight = scope.getIntProperty(0, IntProperty.COVER_WEIGHT)
See also
Obj.getIntProperty(): Base implementation getGoal(): Direct goal accessor
- setIntProperty(coverindex: int, property: IntProperty, value: int)
Set an integer property value on this scope or a cover item.
Overrides Obj.setIntProperty() to provide scope-specific property handling. Automatically maps SCOPE_GOAL to the goal mutator method for convenience.
- Parameters:
coverindex – Index of cover item, or -1 for scope-level properties.
property – Integer property identifier (IntProperty enum).
value – New integer value for the property.
- Raises:
NotImplementedError – If property is not supported or read-only.
Example
>>> # Set scope goal using property interface >>> scope.setIntProperty(-1, IntProperty.SCOPE_GOAL, 95) >>> # Set weight of first cover item >>> scope.setIntProperty(0, IntProperty.COVER_WEIGHT, 10)
See also
Obj.setIntProperty(): Base implementation setGoal(): Direct goal mutator
Coverpoint
A coverpoint measuring coverage of a single variable or expression.
Contains bins created via createBin().
Create via createCoverpoint().
- class ucis.coverpoint.Coverpoint
Coverpoint measuring coverage of a single variable or expression.
Coverpoint represents a SystemVerilog/SystemC/e coverpoint, which measures coverage of a single variable or expression by dividing its value space into discrete bins. Each bin tracks how many times values in that range were sampled.
A coverpoint contains: - Bins: Coverage bins (CVGBIN) representing ranges or specific values - Options: Configuration inherited from CvgScope (at_least, auto_bin_max, etc.) - Goal: Optional coverpoint-level coverage goal
Bin types include: - Regular bins (CVGBIN): Count hits - Ignore bins (IGNOREBIN): Don’t count in coverage - Illegal bins (ILLEGALBIN): Flag as errors
The coverpoint’s coverage percentage is calculated based on how many bins have met their goals (at_least threshold).
Example
>>> # Create coverpoint for an address bus >>> cp = cg.createCoverpoint("cp_addr", src_info, weight=1, ... source=SourceT.SV) >>> cp.setAtLeast(1) # Each bin needs 1+ hit >>> >>> # Add bins for address ranges >>> cp.createBin("low", src_info, at_least=1, count=0, ... rhs="[0:255]", kind=CoverTypeT.CVGBIN) >>> cp.createBin("mid", src_info, at_least=1, count=0, ... rhs="[256:511]", kind=CoverTypeT.CVGBIN) >>> cp.createBin("high", src_info, at_least=1, count=0, ... rhs="[512:1023]", kind=CoverTypeT.CVGBIN) >>> >>> # Query coverage >>> goal = cp.getScopeGoal()
See also
CvgScope: Base class with options (at_least, auto_bin_max, etc.) Covergroup: Parent covergroup container Cross: Cross-product coverage CoverTypeT.CVGBIN: Regular coverage bin type UCIS LRM Section 6.4.3.3 “UCIS_COVERPOINT”
- getScopeGoal() int
Get the coverage goal for this coverpoint.
Returns the target coverage percentage or count for this coverpoint as a whole. This is separate from individual bin goals.
- Returns:
Coverage goal value (interpretation depends on configuration).
Example
>>> goal = cp.getScopeGoal() >>> print(f"Coverpoint goal: {goal}")
See also
setScopeGoal(): Set coverpoint goal getAtLeast(): Get bin-level threshold
- setScopeGoal(goal)
Set the coverage goal for this coverpoint.
Sets the target coverage percentage or count for this coverpoint as a whole.
- Parameters:
goal – Coverage goal value.
Example
>>> cp.setScopeGoal(100) # 100% coverage goal
See also
getScopeGoal(): Query coverpoint goal setAtLeast(): Set bin-level threshold
- createBin(name: str, srcinfo: SourceInfo, at_least: int, count: int, rhs: str, kind=<CoverTypeT.CVGBIN: 1>) CoverIndex
Create a coverage bin within this coverpoint.
Creates a new bin representing a range or set of values for this coverpoint. Bins are the coverage items that track hit counts.
- Parameters:
name – Bin name (e.g., “low”, “high”, “auto[0]”).
srcinfo – Source location where bin is defined.
at_least – Threshold count for bin to be considered covered.
count – Initial hit count (typically 0).
rhs – Right-hand side expression describing bin range (e.g., “[0:255]”).
kind – Bin type (CVGBIN, IGNOREBIN, ILLEGALBIN, DEFAULTBIN). Default is CVGBIN.
- Returns:
CoverIndex reference to the created bin.
Example
>>> # Regular coverage bins >>> low = cp.createBin("low", src_info, at_least=1, count=0, ... rhs="[0:255]", kind=CoverTypeT.CVGBIN) >>> high = cp.createBin("high", src_info, at_least=1, count=0, ... rhs="[256:1023]", kind=CoverTypeT.CVGBIN) >>> >>> # Illegal bin (flags errors) >>> illegal = cp.createBin("illegal", src_info, at_least=0, count=0, ... rhs="[1024:$]", kind=CoverTypeT.ILLEGALBIN)
Note
The method automatically sets up CoverData with appropriate flags (IS_32BIT, HAS_GOAL, HAS_WEIGHT) and initializes goal=1, weight=1.
See also
CoverIndex: Reference to coverage items CoverData: Coverage measurement data CoverTypeT.CVGBIN: Regular bin type CoverTypeT.IGNOREBIN: Ignored bin type CoverTypeT.ILLEGALBIN: Illegal bin type
Cross
Cross-product coverage of two or more coverpoints. Extends
Coverpoint.
Create via createCross().
- class ucis.cross.Cross
Cross-product coverage of multiple coverpoints.
Cross represents a SystemVerilog/SystemC/e cross, which measures coverage of combinations of values from multiple coverpoints. A cross automatically generates bins for the Cartesian product of the crossed coverpoints’ bins.
For example, crossing a 2-bin address coverpoint with a 3-bin data coverpoint creates 2×3=6 cross bins, one for each combination.
Cross extends Coverpoint, so it inherits bin management methods, but its bins represent multi-dimensional combinations rather than single values.
The cross tracks: - Crossed coverpoints: List of constituent coverpoints - Cross bins: Automatically or manually generated combination bins - Options: Inherited from CvgScope (at_least, etc.)
Example
>>> # Create two coverpoints >>> cp_addr = cg.createCoverpoint("cp_addr", src_info, 1, SourceT.SV) >>> cp_addr.createBin("low", src_info, 1, 0, "[0:255]") >>> cp_addr.createBin("high", src_info, 1, 0, "[256:1023]") >>> >>> cp_data = cg.createCoverpoint("cp_data", src_info, 1, SourceT.SV) >>> cp_data.createBin("zero", src_info, 1, 0, "0") >>> cp_data.createBin("nonzero", src_info, 1, 0, "[1:$]") >>> >>> # Create cross (generates 2×2=4 bins automatically) >>> cross = cg.createCross("addr_x_data", src_info, weight=2, ... source=SourceT.SV, ... points_l=[cp_addr, cp_data]) >>> >>> # Query crossed coverpoints >>> num = cross.getNumCrossedCoverpoints() # Returns 2 >>> cp0 = cross.getIthCrossedCoverpoint(0) # Returns cp_addr
Note
Cross bins are named based on the constituent bin names, typically using a separator like “×” or “:”. For example: “low×zero”, “high×nonzero”.
See also
Coverpoint: Base class for bin management Covergroup.createCross(): Create cross coverage CvgScope: Coverage scope with options IntProperty.NUM_CROSSED_CVPS: Number of crossed coverpoints property UCIS LRM Section 6.4.3.4 “UCIS_CROSS”
- getNumCrossedCoverpoints() int
Get the number of coverpoints crossed by this cross.
Returns how many coverpoints were crossed to form this cross coverage. This is the dimensionality of the cross (e.g., 2 for a 2-way cross).
- Returns:
Number of coverpoints in the cross (≥ 2).
Example
>>> cross = cg.createCross("addr_x_data_x_mode", src_info, 1, ... SourceT.SV, [cp_addr, cp_data, cp_mode]) >>> num = cross.getNumCrossedCoverpoints() # Returns 3 >>> print(f"This is a {num}-way cross")
See also
getIthCrossedCoverpoint(): Get specific crossed coverpoint IntProperty.NUM_CROSSED_CVPS: Underlying property
- getIthCrossedCoverpoint(index) Coverpoint
Get the i-th coverpoint crossed by this cross.
Returns one of the coverpoints that were crossed to form this cross coverage, indexed by position in the cross definition.
- Parameters:
index – Zero-based index of the coverpoint (0 to N-1, where N is the number of crossed coverpoints).
- Returns:
Coverpoint object at the specified index.
Example
>>> # Iterate all crossed coverpoints >>> num = cross.getNumCrossedCoverpoints() >>> for i in range(num): ... cp = cross.getIthCrossedCoverpoint(i) ... print(f"Crossed coverpoint {i}: {cp.getName()}")
See also
getNumCrossedCoverpoints(): Get total number of coverpoints Covergroup.createCross(): Specify crossed coverpoints
CvgBinScope
Normal bin scope for SystemVerilog covergroups.
- class ucis.cvg_bin_scope.CvgBinScope
Base class for coverage bin scopes.
CvgBinScope is a specialized coverage scope class used for certain types of bins or bin-like structures that need scope-level representation rather than being simple cover items.
This class extends CvgScope, inheriting all coverpoint/cross options (at_least, auto_bin_max, detect_overlap, etc.), but is used for specialized bin-related scopes in the UCIS hierarchy.
Note
This is primarily a structural class in the type hierarchy. Most coverage bins are represented as cover items (CoverItem) accessed via CoverIndex, not as scopes. CvgBinScope is used for special cases where bin-like entities need to be scopes.
Example
>>> # CvgBinScope is typically not directly instantiated by users >>> # It's used internally by the UCIS implementation for specialized >>> # bin scope structures
See also
CvgScope: Base coverage scope class CoverItem: Regular coverage items (bins) CoverIndex: Access to coverage items Coverpoint: Coverpoint containing bins
IgnoreBinScope
Scope representing a SystemVerilog ignore_bins declaration.
- class ucis.ignore_bin_scope.IgnoreBinScope
Scope for ignore bins in functional coverage.
IgnoreBinScope represents bins that should be ignored in coverage calculations. Ignore bins are used in SystemVerilog covergroups to exclude certain value ranges or combinations from coverage metrics.
Ignore bins: - Do not contribute to coverage percentage calculations - Are not counted as “covered” or “uncovered” - Serve to document intentionally uncovered cases - Help focus coverage on meaningful scenarios
Ignore bins are typically created with the CoverTypeT.IGNOREBIN type and can be treated as specialized coverage scopes in some implementations.
Example
>>> # Ignore bins are typically created on coverpoints >>> cp = cg.createCoverpoint("cp_addr", src_info, 1, SourceT.SV) >>> >>> # Create ignore bin for reserved address range >>> ignore_bin = cp.createBin( ... "ignore_reserved", ... src_info, ... at_least=0, # Not counted ... count=0, ... rhs="[1000:1023]", ... kind=CoverTypeT.IGNOREBIN)
Note
Most implementations treat ignore bins as cover items (CoverItem) rather than scopes. IgnoreBinScope exists for implementations that need scope-level representation of ignore bins.
See also
CvgScope: Base coverage scope class IllegalBinScope: Illegal bin scope CoverTypeT.IGNOREBIN: Ignore bin type Coverpoint.createBin(): Create bins including ignore bins
IllegalBinScope
Scope representing a SystemVerilog illegal_bins declaration.
- class ucis.illegal_bin_scope.IllegalBinScope
Scope for illegal bins in functional coverage.
IllegalBinScope represents bins that should never be hit during normal operation. Illegal bins are used in SystemVerilog covergroups to flag error conditions, unexpected value combinations, or design violations.
Illegal bins: - Should remain at zero hits during correct operation - Any hits typically indicate a design bug or incorrect stimulus - Are reported as errors or warnings by coverage tools - Do not contribute to coverage percentage calculations
When an illegal bin is hit, coverage tools typically report it as a coverage violation, helping identify design or verification issues.
Example
>>> # Illegal bins flag error conditions >>> cp = cg.createCoverpoint("cp_opcode", src_info, 1, SourceT.SV) >>> >>> # Create illegal bin for reserved opcodes >>> illegal_bin = cp.createBin( ... "illegal_reserved", ... src_info, ... at_least=0, # Should stay at 0 ... count=0, ... rhs="[8'hF0:8'hFF]", # Reserved range ... kind=CoverTypeT.ILLEGALBIN) >>> >>> # Check for violations >>> data = illegal_bin.getCoverData() >>> if data.data > 0: ... print(f"ERROR: Illegal bin hit {data.data} times!")
Note
Most implementations treat illegal bins as cover items (CoverItem) rather than scopes. IllegalBinScope exists for implementations that need scope-level representation of illegal bins.
See also
CvgScope: Base coverage scope class IgnoreBinScope: Ignore bin scope CoverTypeT.ILLEGALBIN: Illegal bin type Coverpoint.createBin(): Create bins including illegal bins
Design Hierarchy Scopes
DUScope
Design unit (module/entity/package) definition. DU scopes act as templates
for instances. Create via createScope() with
DU_MODULE (or other DU_* type).
- class ucis.du_scope.DUScope
Design unit (DU) definition scope.
DUScope represents a design unit definition in the UCIS hierarchy. Design units are the “types” or templates that instances instantiate. They contain structural information about the design unit but no instance-specific data.
Design unit types include: - DU_MODULE: Verilog/SystemVerilog module definition - DU_ARCH: VHDL architecture definition - DU_PACKAGE: HDL package definition - DU_PROGRAM: SystemVerilog program definition - DU_INTERFACE: SystemVerilog interface definition
A DU scope stores: - Structural hierarchy of the design unit - Statement/branch/condition definitions - Signature for unique identification
The signature uniquely identifies the DU definition, allowing tools to match instances to their design units across different test runs or compilations.
Example
>>> # Design units are typically created automatically by tools >>> # Access DU from an instance >>> du = instance.getInstanceDu() >>> print(f"Design unit: {du.getName()}") >>> >>> # Get/set DU signature >>> sig = du.getSignature() >>> du.setSignature("module:core:v1.0:checksum_abc123") >>> >>> # Query design unit type >>> du_type = du.getType() # Returns ScopeTypeT.DU_MODULE, etc.
Note
Design units are typically created by EDA tools during elaboration or compilation. User code usually accesses them via instance references rather than creating them directly.
See also
InstanceScope: Instance referencing this DU ScopeTypeT.DU_MODULE: Module design unit type ScopeTypeT.DU_ARCH: Architecture design unit type StrProperty.DU_SIGNATURE: Signature property UCIS LRM Section 6.3.4 “Design Unit Scopes”
- getSignature()
Get the signature identifying this design unit.
Returns a signature string that uniquely identifies this design unit definition. Signatures enable tools to match instances to design units across different simulations and database merges.
The signature format is tool-specific but typically includes the design unit name, version, and/or checksum of the source code.
- Returns:
Signature string, or None if not set.
- Raises:
UnimplError – Not implemented in base class or specific backend.
Example
>>> sig = du.getSignature() >>> print(f"DU signature: {sig}") >>> >>> # Signatures help match instances across runs >>> if du.getSignature() == expected_sig: ... print("Design unit matches expected version")
See also
setSignature(): Set the signature StrProperty.DU_SIGNATURE: Underlying property
- setSignature(sig)
Set the signature identifying this design unit.
Sets a signature string that uniquely identifies this design unit. Tools use signatures to ensure instances refer to the correct DU version when merging databases or reloading data.
- Parameters:
sig – Signature string. Format is tool-specific but should uniquely identify the DU definition.
- Raises:
UnimplError – Not implemented in base class or specific backend.
Example
>>> # Set signature with module name and checksum >>> du.setSignature("module:my_core:v2.1:md5_abc123def456") >>> >>> # Or use file path and timestamp >>> du.setSignature("file:rtl/core.sv:2024-01-15T10:30:00")
See also
getSignature(): Query the signature
- getStringProperty(coverindex: int, property: StrProperty) str
Get a string property value from this object.
Retrieves string-valued properties such as names, comments, file paths, and other textual attributes.
- Parameters:
coverindex – Index of cover item within parent scope. Use -1 to apply the property to the scope itself rather than a specific cover item.
property – String property identifier from the StrProperty enumeration, such as NAME, COMMENT, FILE_NAME, etc.
- Returns:
The string value of the requested property.
- Raises:
UnimplError – If the property is not implemented for this object type.
ValueError – If the property is not applicable to this object type.
Example
>>> # Get the name of a scope >>> name = scope.getStringProperty(-1, StrProperty.NAME) >>> # Get a comment on a cover item >>> comment = scope.getStringProperty(0, StrProperty.COMMENT)
See also
setStringProperty(): Set string property values UCIS LRM Section 8.3.9 “ucis_GetStringProperty”
- setStringProperty(coverindex: int, property: StrProperty, value: str)
Set a string property value on this object.
Modifies string-valued properties such as names, comments, and other textual attributes.
- Parameters:
coverindex – Index of cover item within parent scope. Use -1 to apply the property to the scope itself rather than a specific cover item.
property – String property identifier from the StrProperty enumeration, such as NAME, COMMENT, etc.
value – New string value for the property.
- Raises:
UnimplError – If the property is not implemented for this object type.
ValueError – If the property is not applicable or read-only.
Example
>>> # Set a comment on a scope >>> scope.setStringProperty(-1, StrProperty.COMMENT, "Main test scope") >>> # Set a comment on a specific cover item >>> scope.setStringProperty(0, StrProperty.COMMENT, "Edge case")
Note
Some string properties like NAME may be read-only after object creation to maintain data model consistency.
See also
getStringProperty(): Get string property values UCIS LRM Section 8.3.10 “ucis_SetStringProperty”
- accept(v)
Accept a visitor for traversing the UCIS object hierarchy.
Implements the Visitor design pattern, allowing external traversal and processing of the UCIS object tree without modifying the object classes. Visitors can implement operations like reporting, merging, filtering, or custom analysis.
- Parameters:
v – Visitor object implementing the appropriate visit methods for each object type (visitScope, visitCoverItem, etc.).
- Raises:
UnimplError – If the visitor pattern is not implemented.
Example
>>> class MyVisitor: ... def visitScope(self, scope): ... print(f"Visiting scope: {scope.getName()}") ... >>> visitor = MyVisitor() >>> scope.accept(visitor)
Note
The visitor pattern enables separation of algorithms from the object structure they operate on, facilitating extensibility without modifying core classes.
See also
Visitor design pattern documentation
InstanceScope
A design hierarchy instance. Points back to its design unit via
getInstanceDu(). Create via
createInstance().
- class ucis.instance_scope.InstanceScope
Design hierarchy instance scope.
InstanceScope represents a design instance in the UCIS hierarchy, typically corresponding to a module instance, architecture instance, program instance, or other instantiated design unit in the HDL source.
Instances form the structural backbone of the UCIS database, mirroring the design hierarchy. Each instance references its design unit (DU) definition and contains coverage data specific to that instance.
Key characteristics: - Scope type: INSTANCE (or specialized types like PROGRAM, PACKAGE, INTERFACE) - Contains code coverage items (statements, branches, conditions, etc.) - References a design unit (DU) scope for structural information - May contain child instances and coverage scopes
The instance hierarchy typically follows the design’s module instantiation tree, with the root instance representing the top-level testbench or DUT.
Example
>>> # Create instance hierarchy >>> top = db.createInstance("top", None, src_info, weight=1, ... source=SourceT.SV, duName="top_module") >>> >>> # Create child instance >>> child = top.createInstance("u_core", src_info, weight=1, ... source=SourceT.SV, duName="core") >>> >>> # Get design unit reference >>> du = child.getInstanceDu() >>> print(f"Design unit: {du.getName()}") >>> >>> # Access code coverage items >>> for i in range(child.getNumCovers()): ... item = child.getIthCoverItem(i) ... stmt_idx = item.getStmtIndex()
See also
Scope: Base scope class DUScope: Design unit definition CoverItem: Coverage items within instance ScopeTypeT.INSTANCE: Instance scope type UCIS LRM Section 6.3.1 “Instance Hierarchy”
- getIthCoverItem(i) CoverItem
Get the i-th coverage item in this instance.
Returns a specific coverage item (statement, branch, condition, etc.) by index within this instance scope.
- Parameters:
i – Zero-based index of the coverage item (0 to numCovers-1).
- Returns:
CoverItem object at the specified index.
- Raises:
UnimplError – Not implemented in base class or specific backend.
Example
>>> # Iterate all coverage items in instance >>> num_items = instance.getNumCovers() >>> for i in range(num_items): ... item = instance.getIthCoverItem(i) ... stmt_idx = item.getStmtIndex() ... data = instance.getCoverData(i) ... print(f"Statement {stmt_idx}: {data.data} hits")
See also
Scope.getNumCovers(): Get total number of coverage items CoverItem: Coverage item class
- getInstanceDu() Scope
Get the design unit (DU) scope for this instance.
Returns the design unit scope that defines the structural template for this instance. The DU scope contains the “type” information (module definition, architecture, etc.) while the instance contains the “instance-specific” coverage data.
- Returns:
DUScope object representing the design unit, or None if no DU is associated.
- Raises:
UnimplError – Not implemented in base class or specific backend.
Example
>>> # Get design unit for an instance >>> du = instance.getInstanceDu() >>> if du: ... print(f"Instance type: {du.getName()}") ... sig = du.getSignature() # Get DU signature
Note
In VHDL designs, the DU represents the entity/architecture pair. In Verilog/SystemVerilog, it represents the module definition.
See also
DUScope: Design unit scope class Scope.createInstance(): Create instances with DU references UCIS LRM Section 6.3.4 “Design Unit Scopes”
- setIntProperty(coverindex: int, property: IntProperty, value: int)
Set an integer property value on this scope or a cover item.
Overrides Obj.setIntProperty() to provide scope-specific property handling. Automatically maps SCOPE_GOAL to the goal mutator method for convenience.
- Parameters:
coverindex – Index of cover item, or -1 for scope-level properties.
property – Integer property identifier (IntProperty enum).
value – New integer value for the property.
- Raises:
NotImplementedError – If property is not supported or read-only.
Example
>>> # Set scope goal using property interface >>> scope.setIntProperty(-1, IntProperty.SCOPE_GOAL, 95) >>> # Set weight of first cover item >>> scope.setIntProperty(0, IntProperty.COVER_WEIGHT, 10)
See also
Obj.setIntProperty(): Base implementation setGoal(): Direct goal mutator
- getIntProperty(coverindex: int, property: IntProperty) int
Get an integer property value from this scope or a cover item.
Overrides Obj.getIntProperty() to provide scope-specific property handling. Automatically maps SCOPE_GOAL to the goal accessor method for convenience.
- Parameters:
coverindex – Index of cover item, or -1 for scope-level properties.
property – Integer property identifier (IntProperty enum).
- Returns:
Integer value of the requested property.
- Raises:
NotImplementedError – If property is not supported.
Example
>>> # Get scope goal using property interface >>> goal = scope.getIntProperty(-1, IntProperty.SCOPE_GOAL) >>> # Get weight of first cover item >>> weight = scope.getIntProperty(0, IntProperty.COVER_WEIGHT)
See also
Obj.getIntProperty(): Base implementation getGoal(): Direct goal accessor
Cover Items
CoverItem
Base class for bins — the leaf-level coverage measurements within coverpoints, crosses, and code coverage scopes.
- class ucis.cover_item.CoverItem
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”
- getStmtIndex() 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
- setStmtIndex(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.
- Parameters:
i – Statement index (non-negative integer).
- Raises:
UnimplError – Not implemented in base class or specific backend.
See also
getStmtIndex(): Query statement index
CoverData
Holds the hit count, goal, and status flags for one cover item.
Passed to createBin() and
returned by getCoverData().
- class ucis.cover_data.CoverData(type: CoverTypeT, flags)
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.
- type
Coverage type identifying the metric category.
- Type:
- flags
Bitwise flags controlling data interpretation.
- Type:
Example
>>> from ucis.cover_flags_t 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”
Create coverage data container.
- Parameters:
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)
Value Objects
SourceInfo
Bundles a FileHandle with a line number and token
offset to identify where a scope or bin was declared in source.
- class ucis.source_info.SourceInfo(file: FileHandle, line: int, token: int)
Source code location information for UCIS objects.
SourceInfo encapsulates the location in HDL source code where a coverage object (scope, cover item, etc.) is defined. This includes the source file, line number, and column/token position.
Source information enables: - Traceability from coverage data back to source code - Source-level coverage visualization in IDEs/editors - Navigation from coverage reports to code - Debugging and analysis of uncovered items
SourceInfo objects are typically provided when creating scopes, cover items, and other UCIS objects. They can be None/NULL if source location is unknown or not applicable.
- file
Handle to the source file, or None if not available.
- Type:
FileHandle
Example
>>> # Create source location for line 42, column 10 of a file >>> fh = db.createFileHandle("counter.sv", "/project/rtl") >>> src = SourceInfo(fh, 42, 10) >>> # Use when creating coverage objects >>> scope = parent.createScope("counter", src, 1, SourceT.SV, ... ScopeTypeT.INSTANCE, 0)
Note
Token/column position interpretation may vary by tool. A value of 0 typically indicates “start of line” or “not specified”.
See also
FileHandle: Source file reference Scope.createScope(): Source info used in scope creation UCIS LRM Section 8.12 “Coverage Source File Functions”
Create a source location reference.
- Parameters:
file – FileHandle referencing the source file, or None if file is not known or not applicable.
line – Line number in the source file (1-based). Use 0 if line number is not known or not applicable.
token – Token/column position on the line (0-based). Use 0 for start of line or if position is not known.
Example
>>> # Known file, line, and column >>> src = SourceInfo(file_handle, 100, 5) >>> # Known file and line only >>> src = SourceInfo(file_handle, 100, 0) >>> # No source information available >>> src = None # Can pass None to creation methods
TestData
Carries test metadata (status, tool, date, seed, …) and is passed to
setTestData().
- class ucis.test_data.TestData(teststatus, toolcategory: str, date: str, simtime: float = 0.0, timeunit: str = 'ns', runcwd: str = '.', cputime: float = 0.0, seed: str = '0', cmd: str = '', args: str = '', compulsory: int = 0, user: str = 'user', cost: float = 0.0)
Test run metadata container.
TestData encapsulates all metadata associated with a test run, including execution status, timing information, command line, environment details, and resource usage.
This data is typically stored in history nodes of type TEST and provides complete traceability of test execution for regression analysis and coverage debugging.
- teststatus
Test execution status (OK, ERROR, etc.)
- Type:
Example
>>> from ucis.test_status_t import TestStatusT >>> # Create test data for successful run >>> test_data = TestData( ... teststatus=TestStatusT.OK, ... toolcategory="simulator", ... date="2024-01-15T10:30:00", ... simtime=1000000.0, ... timeunit="ns", ... runcwd="/workspace/tests", ... cputime=45.2, ... seed="12345", ... cmd="vsim", ... args="-c -do run.do", ... compulsory=1, ... user="engineer", ... cost=1.0) >>> >>> # Apply to history node >>> hist_node.setTestData(test_data)
See also
HistoryNode.setTestData(): Apply test data to history node TestStatusT: Test status enumeration HistoryNodeKind.TEST: Test history node type UCIS LRM Section 4.13 “History Nodes”
Create test metadata container.
- Parameters:
teststatus – Test execution status (TestStatusT).
toolcategory – Tool category string.
date – Execution date/timestamp string.
simtime – Simulation time value. Default 0.0.
timeunit – Time unit string (“ns”, “ps”, etc.). Default “ns”.
runcwd – Working directory path. Default “.”.
cputime – CPU seconds consumed. Default 0.0.
seed – Random seed string. Default “0”.
cmd – Command string. Default “”.
args – Arguments string. Default “”.
compulsory – Compulsory flag (0/1). Default 0.
user – Username string. Default “user”.
cost – Cost metric. Default 0.0.
Enumerations
ScopeTypeT
Identifies the type of every scope in the hierarchy. Used as a filter mask
in scopes() and as a required argument to scope
creation methods.
- class ucis.scope_type_t.ScopeTypeT(*values)
Scope type identifiers for UCIS hierarchical objects.
Defines the enumeration of scope types in the UCIS coverage model. Scopes represent hierarchical containers that organize coverage data and design structure. Each scope has a unique type that determines its purpose and the operations that can be performed on it.
The scope type is one of the two components (along with name) that forms the primary key for UCIS objects. Types are implemented as bit flags to support efficient type checking and categorization.
Scope types fall into several categories: - HDL Hierarchy: INSTANCE, PROCESS, BLOCK, FUNCTION, etc. - Design Units: DU_MODULE, DU_ARCH, DU_PACKAGE, DU_PROGRAM, DU_INTERFACE - Functional Coverage: COVERGROUP, COVERINSTANCE, COVERPOINT, CROSS - Code Coverage: TOGGLE, BRANCH, EXPR, COND, BLOCK - Assertions: ASSERT, COVER - FSM Coverage: FSM, FSM_STATES, FSM_TRANS
Note
Types are mutually exclusive - each scope has exactly one type. The IntFlag base enables bitwise operations for type masks.
See also
Scope.getType(): Get the type of a scope UCIS LRM Section 5.1.1 “Scopes or hierarchical nodes” UCIS LRM Section 5.2 “Primary key design”
- TOGGLE = 1
Toggle coverage scope tracking signal transitions.
- BRANCH = 2
Branch coverage scope for conditional statements.
- EXPR = 4
Expression coverage scope for complex expressions.
- COND = 8
Condition coverage scope for boolean sub-expressions.
- INSTANCE = 16
Design hierarchy instance (module/entity instantiation).
- PROCESS = 32
HDL process scope (VHDL process, Verilog always block).
- BLOCK = 64
HDL block scope (VHDL block, Verilog begin-end).
- FUNCTION = 128
Function scope in HDL code.
- FORKJOIN = 256
Verilog fork-join parallel block.
- GENERATE = 512
HDL generate block (parametric hierarchy).
- GENERIC = 1024
Generic scope type for unclassified scopes.
- CLASS = 2048
Object-oriented class type scope (SystemVerilog).
- COVERGROUP = 4096
Covergroup type definition scope (SystemVerilog).
- COVERINSTANCE = 8192
Covergroup instance scope (per-instance coverage).
- COVERPOINT = 16384
Coverpoint scope within a covergroup.
- CROSS = 32768
Cross coverage scope crossing multiple coverpoints.
- COVER = 65536
Assertion cover directive (SVA/PSL cover statement).
- ASSERT = 131072
Assertion directive (SVA/PSL assert statement).
- PROGRAM = 262144
SystemVerilog program instance.
- PACKAGE = 524288
Package scope (SystemVerilog/VHDL package).
- TASK = 1048576
Task scope in HDL code.
- INTERFACE = 2097152
SystemVerilog interface instance.
- FSM = 4194304
Finite state machine coverage scope.
- DU_MODULE = 16777216
Design unit for module/entity definition.
- DU_ARCH = 33554432
Design unit for VHDL architecture.
- DU_PACKAGE = 67108864
Design unit for package definition.
- DU_PROGRAM = 134217728
Design unit for SystemVerilog program.
- DU_INTERFACE = 268435456
Design unit for SystemVerilog interface.
- FSM_STATES = 536870912
FSM state coverage scope.
- FSM_TRANS = 1073741824
FSM transition coverage scope.
- COVBLOCK = 2147483648
Block coverage scope.
- CVGBINSCOPE = 4294967296
SystemVerilog normal bin scope.
- ILLEGALBINSCOPE = 8589934592
SystemVerilog illegal bin scope.
- IGNOREBINSCOPE = 17179869184
SystemVerilog ignore bin scope.
- RESERVEDSCOPE = 18374686479671623680
Reserved for future use.
- SCOPE_ERROR = 0
Error return code indicating invalid scope type.
- ALL = 281474976710655
Mask for all valid scope types.
- static DU_ANY(t)
Check if a scope type is any design unit type.
Helper function to test whether a scope type represents a design unit (DU_MODULE, DU_ARCH, DU_PACKAGE, DU_PROGRAM, or DU_INTERFACE).
- Parameters:
t – Scope type value to test (ScopeTypeT).
- Returns:
True if the type is any design unit type, False otherwise.
Example
>>> if ScopeTypeT.DU_ANY(scope.getType()): ... print("This is a design unit")
CoverTypeT
Identifies the coverage type of every cover item (bin). Used as a filter
mask in coverItems().
- class ucis.cover_type_t.CoverTypeT(*values)
Coverage type identifiers for cover items.
Defines the enumeration of coverage types used to classify cover items (bins) in the UCIS data model. The coverage type indicates what kind of coverage metric the item represents, such as functional coverage bins, code coverage, or assertion results.
Coverage types are implemented as bit flags to support efficient type checking and categorization. Each cover item has exactly one coverage type that determines its semantics and how coverage tools interpret the data.
Types fall into several categories: - Functional Coverage: CVGBIN (SystemVerilog covergroups) - Code Coverage: STMTBIN, BRANCHBIN, EXPRBIN, CONDBIN, TOGGLEBIN, BLOCKBIN - Assertions: ASSERTBIN, COVERBIN, PASSBIN, FAILBIN, VACUOUSBIN, etc. - FSM Coverage: FSMBIN - User-defined: USERBIN, GENERICBIN
Note
Coverage types are distinct from scope types. A scope type defines the hierarchical container, while a coverage type defines the measurement category for individual bins.
See also
CoverItem: Base class for coverage measurements ScopeTypeT: Scope type identifiers UCIS LRM Section 5.3 “Cover Items”
- CVGBIN = 1
SystemVerilog covergroup bin (functional coverage).
- COVERBIN = 2
Cover directive pass count (cover property succeeded).
- ASSERTBIN = 4
Assert directive fail count (assertion violated).
- STMTBIN = 32
Statement coverage bin (line or statement executed).
- BRANCHBIN = 64
Branch coverage bin (conditional branch taken/not taken).
- EXPRBIN = 128
Expression coverage bin (sub-expression evaluation).
- CONDBIN = 256
Condition coverage bin (boolean condition true/false).
- TOGGLEBIN = 512
Toggle coverage bin (signal transition 0->1 or 1->0).
- PASSBIN = 1024
Assert directive pass count (assertion succeeded).
- FSMBIN = 2048
Finite state machine coverage bin (state or transition).
- USERBIN = 4096
User-defined coverage metric.
- GENERICBIN = 4096
Generic user-defined coverage (alias for USERBIN).
- COUNT = 8192
User-defined count metric (not included in coverage percentage).
- FAILBIN = 16384
Cover directive fail count (cover property failed).
- VACUOUSBIN = 32768
Assert vacuous pass count (assertion vacuously true).
- DISABLEDBIN = 65536
Assert disabled count (assertion disabled).
- ATTEMPTBIN = 131072
Assert attempt count (assertion evaluation started).
- ACTIVEBIN = 262144
Assert active thread count (concurrent assertion threads).
- IGNOREBIN = 524288
SystemVerilog ignore bin (excluded from coverage).
- ILLEGALBIN = 1048576
SystemVerilog illegal bin (should not be hit).
- DEFAULTBIN = 2097152
SystemVerilog default bin (auto-generated catch-all).
- PEAKACTIVEBIN = 4194304
Assert peak active thread count (maximum concurrent threads).
- BLOCKBIN = 16777216
Block coverage bin (code block executed).
- USERBITS = 4261412864
Reserved bits for user-defined coverage extensions.
- RESERVEDBIN = 18374686479671623680
Reserved for future use by the UCIS standard.
- ALL = 18446744073709551615
Mask for all cover item types.
CoverFlagsT
Bit flags stored in a CoverData that control
data precision and indicate which optional fields are valid.
- class ucis.cover_flags_t.CoverFlagsT(*values)
Coverage data flags for cover items.
Defines bit flags that control the interpretation and format of coverage data in CoverData objects. Flags indicate which fields are valid, data precision, and coverage item behaviors.
Flags are used to: - Specify data precision (32-bit vs 64-bit vs vector) - Indicate which optional fields are present (goal, weight, limit) - Control exclusion and enablement - Mark coverage status - Store type-specific behaviors (assertion actions, FSM transitions, etc.)
Flags are combined using bitwise OR when creating CoverData objects.
See also
CoverData: Coverage data container using these flags UCIS LRM Section 8.11 “Coveritem Creation and Manipulation”
- IS_32BIT = 1
Coverage data is 32-bit integer.
- IS_64BIT = 2
Coverage data is 64-bit integer.
- IS_VECTOR = 4
Coverage data is bit vector (use bitlen field).
- HAS_GOAL = 8
Goal field is included and meaningful.
- HAS_WEIGHT = 16
Weight field is included and meaningful.
HistoryNodeKind
Discriminates test-run nodes (TEST) from merge nodes (MERGE) in the
database history tree.
- class ucis.history_node_kind.HistoryNodeKind(*values)
History node type identifiers.
Defines the types of history nodes in the UCIS database. History nodes track the provenance of coverage data, recording test runs and database merge operations.
The history node tree represents the lineage of the coverage data: - TEST nodes are leaves representing individual test runs (primary data) - MERGE nodes are internal nodes representing database merge operations
Each coverage database has a history tree showing which tests contributed to the final coverage and how databases were merged together. This enables traceability and regression analysis.
History Node Types:
NONE: Uninitialized or invalid history node
ALL: Special value for iteration (matches all node types)
TEST: Leaf node representing a single test run
MERGE: Internal node representing a merge operation
Example
>>> # Create test history node >>> test_node = db.createHistoryNode( ... parent=None, ... logicalName="regression_test_42", ... physicalName="/results/test42.ucis", ... kind=HistoryNodeKind.TEST) >>> >>> # Create merge node combining two tests >>> merge_node = db.createHistoryNode( ... parent=None, ... logicalName="merged_coverage", ... physicalName="/results/merged.ucis", ... kind=HistoryNodeKind.MERGE) >>> >>> # Iterate all history nodes >>> for node in db.historyNodes(HistoryNodeKind.ALL): ... kind = node.getKind() ... if kind == HistoryNodeKind.TEST: ... print(f"Test: {node.getLogicalName()}") ... elif kind == HistoryNodeKind.MERGE: ... print(f"Merge: {node.getLogicalName()}")
See also
UCIS.createHistoryNode(): Create history nodes UCIS.historyNodes(): Iterate history nodes HistoryNode: History node class (if exists) UCIS LRM Section 4.13 “History Nodes” UCIS LRM Section 8.13 “History Node Management”
- NONE = -1
Uninitialized or invalid history node type.
- ALL = 0
Special value for iteration to match all history node types.
Note
This is used as a filter parameter for iteration; no actual history node object has this type.
- TEST = 1
Test leaf node representing a single test run (primary database).
Test nodes are the leaves of the history tree and represent the original coverage data collected from individual test runs. They contain test metadata such as command line, date, seed, username, etc.
- MERGE = 2
Merge node representing a database merge operation.
Merge nodes are internal nodes in the history tree that represent the combination of multiple coverage databases. They track which databases were merged and enable analysis of coverage contributions.
TestStatusT
Pass/fail status recorded on a test history node.
- class ucis.test_status_t.TestStatusT(*values)
Test execution status enumeration.
Defines the execution status of a test run recorded in a history node. The status indicates whether the test completed successfully or encountered errors, warnings, or other exceptional conditions.
Test status helps identify: - Successfully completed tests (OK) - Tests with warnings or errors - Fatal test failures - Missing or incomplete test data - Data inconsistencies from merging
Status values typically correspond to SystemVerilog severity system tasks ($warning, $error, $fatal) and test infrastructure states.
Example
>>> # Check test status from history node >>> status = test_node.getTestStatus() >>> if status == TestStatusT.OK: ... print("Test passed successfully") >>> elif status == TestStatusT.WARNING: ... print("Test completed with warnings") >>> elif status == TestStatusT.ERROR: ... print("Test had errors") >>> elif status == TestStatusT.FATAL: ... print("Test failed fatally") >>> >>> # Set test status >>> test_node.setTestStatus(TestStatusT.OK) >>> >>> # Filter for passing tests >>> passing_tests = [node for node in db.historyNodes() ... if node.getTestStatus() == TestStatusT.OK]
See also
HistoryNode: History node with test status (if class exists) HistoryNodeKind.TEST: Test history node type UCIS.createHistoryNode(): Create history nodes with status UCIS LRM Section 4.13 “History Nodes”
- OK = 1
Test completed successfully without errors or warnings.
Indicates normal test completion with no issues detected.
- WARNING = 2
Test completed with warnings.
Corresponds to SystemVerilog $warning system task calls. The test ran to completion but encountered non-fatal issues that should be reviewed.
- ERROR = 3
Test encountered errors.
Corresponds to SystemVerilog $error system task calls. The test detected errors but may have continued execution. Results may be suspect.
- FATAL = 4
Test failed with fatal error.
Corresponds to SystemVerilog $fatal system task calls. The test terminated abnormally due to a critical failure. Coverage data may be incomplete or invalid.
- MISSING = 5
Test has not been run yet or data is missing.
Indicates that the test is planned or expected but coverage data has not been collected yet. Used in regression tracking.
- MERGE_ERROR = 6
Test data record was merged with inconsistent data values.
Indicates that during database merging, conflicting or inconsistent data was encountered for this test. The merged results may not be reliable and should be investigated.
SourceT
HDL source language of a scope (VLOG, SV, VHDL, etc.).
- class ucis.source_t.SourceT(*values)
HDL source language type identifiers.
Defines the enumeration of source language types for scopes and objects in the UCIS coverage model. The source type indicates which hardware description language or verification language was used to define the object.
Source types are used to: - Identify the language context of coverage objects - Support language-specific coverage semantics - Enable cross-language coverage integration - Assist tools in language-appropriate formatting
The source type is stored as part of scope metadata and can be queried using the SCOPE_SOURCE_TYPE integer property.
See also
IntProperty.SCOPE_SOURCE_TYPE: Property to get/set source type Scope.createScope(): Source type is specified during scope creation UCIS LRM Section 5.4 “Source Language Types”
- VHDL = 0
VHDL hardware description language.
- VLOG = 1
Verilog hardware description language.
- SV = 2
SystemVerilog hardware description and verification language.
- SYSTEMC = 3
SystemC transaction-level modeling language.
- PSL_VHDL = 4
PSL (Property Specification Language) assertions in VHDL context.
- PSL_VLOG = 5
PSL (Property Specification Language) assertions in Verilog context.
- PSL_SV = 6
PSL (Property Specification Language) assertions in SystemVerilog context.
- PSL_SYSTEMC = 7
PSL (Property Specification Language) assertions in SystemC context.
- E = 8
e verification language (Specman Elite).
- VERA = 9
Vera verification language (OpenVera).
- NONE = 10
Source language is not specified or not applicable.
- OTHER = 11
User-defined or non-standard source language.
- SOURCE_ERROR = 12
Error value indicating invalid source type.
FlagsT
Scope-level flags controlling coverage enablement, exclusion, and other
scope behaviours. Passed as the flags argument to scope creation methods.
- class ucis.flags_t.FlagsT(*values)
Scope and coverage flags for UCIS objects.
Defines bit flags that modify the behavior and interpretation of scopes and coverage objects. Flags can be combined using bitwise OR operations to set multiple flags simultaneously.
Flags control various aspects: - Coverage enablement: Which coverage types are collected - Scope properties: Exclusion, instantiation behavior - Covergroup options: Auto-generation, type of coverage - Assertion properties: Immediate vs. concurrent
Flags are typically set during scope creation and can be queried or modified using scope flag methods. Multiple flags can be active simultaneously.
See also
Scope.createScope(): Flags specified during scope creation UCIS LRM Section 8.5.19 “ucis_GetScopeFlag” UCIS LRM Section 8.5.20 “ucis_SetScopeFlag”
- INST_ONCE = 1
Instance is instantiated only once; code coverage stored in instance only.
- ENABLED_STMT = 2
Statement coverage is collected for this scope.
- ENABLED_BRANCH = 4
Branch coverage is collected for this scope.
- ENABLED_COND = 8
Condition coverage is collected for this scope.
- ENABLED_EXPR = 16
Expression coverage is collected for this scope.
- ENABLED_FSM = 32
FSM (finite state machine) coverage is collected for this scope.
- ENABLED_TOGGLE = 64
Toggle coverage is collected for this scope.
- ENABLED_BLOCK = 8388608
Block coverage is collected for this scope.
- SCOPE_UNDER_DU = 256
Scope is located under a design unit scope (read-only property).
- SCOPE_EXCLUDED = 512
Scope is excluded from coverage calculations.
- SCOPE_PRAGMA_EXCLUDED = 1024
Scope excluded by pragma directive in source code.
- SCOPE_PRAGMA_CLEARED = 2048
Pragma exclusion has been cleared/removed.
- SCOPE_SPECIALIZED = 4096
Scope has specialized coverage semantics.
- UOR_SAFE_SCOPE = 8192
Scope is safe for Universal Object Recognition.
- UOR_SAFE_SCOPE_ALLCOVERS = 16384
Scope and all cover items are safe for Universal Object Recognition.
- IS_TOP_NODE = 65536
Scope is a top-level node in the hierarchy.
- IS_IMMEDIATE_ASSERT = 65536
Assertion is immediate (not concurrent).
- SCOPE_CVG_AUTO = 65536
Covergroup uses auto-generated bins.
- SCOPE_CVG_SCALAR = 131072
Coverpoint covers scalar (single-bit) values.
- SCOPE_CVG_VECTOR = 262144
Coverpoint covers vector (multi-bit) values.
- SCOPE_CVG_TRANSITION = 524288
Coverpoint covers state transitions.
- SCOPE_IFF_EXISTS = 1048576
Scope has an ‘iff’ (if and only if) condition.
- SCOPE_BLOCK_ISBRANCH = 16777216
Block scope represents a branch decision.