Verification and Coverage

Coverage is a key metric we use to evaluate how well-verified a design is. We collect and analyze code coverage to identify areas of the design that aren’t exercised. We use assertion and functional coverage to ensure that key conditions are exercised. Combined with the right meta-data, such as test name, we can derive higher-level information such as a small set of tests that will exercise a design change.

Many design verification tools and frameworks support capturing and working with coverage metrics. For example, cocotb-coverage and AVL each support capturing functional coverage data, saving it to a file, and performing post-processing. Verilator supports capturing code and assertion coverage, and the major EDA companies have solutions as well.

But, all of these are independent. How can I view and analyze Verilator code coverage and AVL functional coverage together?

Standards: UCIS

A unique aspect of verification coverage is that we have are larger set of metrics than software projects typically use. Software projects tend to focus on code coverage, while design verification is also interested in functional coverage, FSM coverage, and assertion coverage.

Back in 2012, the Accellera EDA standards body released UCIS, the Unified Coverage Interoperability Standard. UCIS defines a data model and an API for interacting with all the types of coverage data that verification engineers work with. It also defines an XML interchange format supported by some tools and the FC4SC library that implements functional coverage for SystemC.

Having a common API enables the classic separation of concerns that other common APIs, such as LSP and MCP enable. Instead of developing analysis capabilities for each and every coverage format, we can create tools that use the UCIS API, and converters to map coverage formats into the UCIS data model.

Open Source: PyUCIS

I initially created the PyUCIS project because I needed a way to work with coverage data captured by the PyVSC library that I was also working on. At the time, I focused on support for functional coverage (coverpoints, cross-coverage, etc) since that was the data PyVSC produced.

As I noted in the introduction, AI-driven productivity gains have me revisiting projects like PyUCIS to add new features and provide more-comprehensive support. But, also, to ensure that the libraries are properly AI-enabled for users. We’ll cover some of these new feature areas in future posts, but this post focuses on AI enablement.

Three Levels of AI Enablement

I’ve gradually come to apply a three-level approach for enabling a tool for AI agent access that reflect successively-deeper levels of integration with the tool.

AI-Friendly CLI

The first level of integration is via the command-line interface (CLI). AI agents, such as Copilot, Codex, and Claude Code, excel at using command-line tools. Best practices for enhancing the CLI to be AI-friendly include:

• Providing granular data-manipulation commands with good help messages
• Providing JSON output
• Providing a pointer to a SKILL.md file

In the case of PyUCIS, our primary interest is in enabling an AI agent to analyze coverage data, so we focus most of our efforts on the show sub-commands.

usage: ucis show [-h]
                 ...

positional arguments:
    summary             Display overall coverage summary
    gaps                Display coverage gaps (uncovered bins and coverpoints)
    covergroups         Display detailed covergroup information
    bins                Display bin-level coverage details
    tests               Display test execution information
    hierarchy           Display design hierarchy structure
    metrics             Display coverage metrics and statistics
    compare             Compare coverage between two databases
    hotspots            Identify coverage hotspots and high-value targets
    code-coverage       Display code coverage with support for LCOV/Cobertura formats
    assertions          Display assertion coverage information
    toggle              Display toggle coverage information

options:
  -h, --help            show this help message and exit

LLMs often work more effectively with JSON data vs unstructured (or, arbitrarily-structured) text. JSON data has a regular structure and associates meta-data with various elements of the output (eg ‘name’, ‘id’, etc). In addition, an LLM can leverage tools like jq to efficiently slice and dice it. Consequently, it’s a very good practice to support JSON output. Enabling this with a specific switch is fine, since most humans won’t want to see JSON.

Agent Skills is an emerging standard for providing instructions to agents.

======================================================================
PyUCIS AgentSkills Information
======================================================================

Skill Definition: /home/.../ucis/share/SKILL.md

Note for LLM Agents:
  This file contains detailed information about PyUCIS capabilities,
  usage patterns, and best practices. LLM agents should reference
  this skill to better understand how to work with UCIS coverage
  databases and leverage PyUCIS tools effectively.

For more information, visit: https://agentskills.io
======================================================================

A skill for a tool provides examples and more in-depth instructions on tool workflows. I like to advertise how to find the tool’s skill in the help message, since AI agents often check this first.

Model Context Protocol

The Model Context Protocol (MCP) is a JSON RPC-based communication protocol that allows AI agents to run external operations. MCP excels in situations where operation setup times are long. For example, loading a waveform database often takes significant time. The overhead of doing so every time the Agent wishes to look at a waveform value is prohibitive. A waveform MCP server, such as pywellen-mcp, loads the waveform database once and allows the Agent to perform many queries.

PyUCIS provides a MCP server with a range of tools, including:

Database Operations

• open_database: Load UCIS databases in XML, YAML, or UCIS binary formats
• close_database: Clean up database resources
• list_databases: List all currently open databases
• get_database_info: Retrieve database metadata and statistics

Coverage Analysis Tools

• get_coverage_summary: Overall coverage statistics by type (statement, branch, etc.)
• get_coverage_gaps: Identify uncovered or low-coverage items with configurable thresholds
• get_covergroups: Retrieve covergroup details with optional bin information
• get_bins: Detailed bin-level coverage with advanced filtering capabilities
• get_tests: Test execution information and results
• get_hierarchy: Navigate and explore the design hierarchy
• get_metrics: Advanced coverage metrics and analysis

Advanced Features

• compare_databases: Compare two databases for regression analysis and coverage deltas
• get_hotspots: Identify high-value coverage targets for optimization
• get_code_coverage: Export code coverage in multiple formats (LCOV, Cobertura, JaCoCo, Clover)
• get_assertions: SVA/PSL assertion coverage details
• get_toggle_coverage: Signal toggle coverage information

Given the speed of the PyUCIS SQLite database, I’ll be interested in point at which using the MCP server becomes beneficial.

API

An API provides an AI agent the most-detailed access to a tool’s capabilities. Both the difficulty of producing an API and the difficult of an AI agent using it depends heavily on the tool’s implementation language. For example, Python is often fairly easy on both counts, since producing an API typically means documenting functions that we’ve already created to implement the tool, and AI agents can simply load the module and go. On the other hand, a compiled languages like C/C++ will likely require explicit action to define and expose an API, and AI agents will need to use the language toolchain to compile, link, and run with the API.

Conclusion and Next Steps

Design verification heavily relies on good coverage data to assess completeness, and AI can play a critical role in analysis. PyUCIS implements the Accellera UCIS API, and supports AI agents via the CLI and a built-in MCP server. As previously mentioned, you can look at the AI-assisted workflow example in the PyUCIS repository to get ideas of how to work with coverage data using the PyUCIS library and AI agents. Next time, we’ll shift focus to look at some of the other new and improved features in PyUCIS that AI agents are helping to rapidly develop.

EDA Software and Domain Expertise

Electronic Design Automation (EDA) software is a unique market. Like any other complex software, developing it requires strong software engineering skills. But, developing good EDA software also requires deep knowledge of the silicon engineering domain.

In my experience with commercial EDA, these two roles are generally handled by different people. Software engineering is handled by teams of software developers that, thinking simplistically, need to know very little about silicon engineering. Silicon engineering expertise is often represented by the product engineering role. This role is responsible for understanding the domain, and the user’s perspective on it, and translating that into requirements that the software engineering team can implement. In practice, of course, each of these disciplines has some cross-over. EDA software engineers have varying degrees of expertise in silicon engineering, and product engineers have varying degrees of software engineering expertise.

AI and Open Source EDA

An open source EDA developer typically doesn’t have the luxury of focusing on a single domain. Open source EDA developers often start from a vision – whether that’s simply the existence of open source tools for a given portion of the silicon engineering workflow, or a vision of a new way to approach a part of that workflow. But, very quickly, the developer must pivot and focus of the nuts and bolts of realizing this vision in code.

My experience, increasingly so over the last 4-6 months, has been that AI allows me to focus much more energy on the Product Engineering aspects of open source EDA, while delegating much of the software engineering aspects.

AI and Open Source EDA Developers

If you’re an open source EDA developer, AI enables you to spend a greater portion of your time in Product Engineer mode. With good requirements and review (all key Product Engineer skills), the bulk of software engineering tasks can be delegated to an agent. Here are a few things to consider as you look for AI opportunities in your project.

Develop ‘Nice to Have’ Features

Being an open source developer fosters a mentality of scarcity, if your experience is anything like mine. Ruthless prioritization is the only way to ensure that something with sufficiently-broad application can be produced by a single developer. ‘Nice to have’ features must be deferred – potentially forever.

AI nicely inverts this equation. When the primary cost of a new feature is specification, it becomes much easier to justify adding helpful features: better error handling, more output formats, etc.

More Communication

Communication tasks such as documentation, project websites, and project news is a task that often gets de-prioritized. After all, we need to get key features developed!

AI-created content has come a long ways. One can argue it still has a ways to go, but it’s often quite good for technical documentation. It works well in incremental mode to document features as they’re developed, but also to improve documentation for an existing codebase. While we should always be cautious about passing off AI-generated ‘slop’ as useful documentation, my current experience is that AI-generated docs are far better than no documentation at all. I’m also finding that providing a little structure and guidance goes a long way in getting better results.

Consider the Agent Experience

As a developer, it’s key to consider how your user will experience your project. Increasingly, you can assume that your users will be using an AI agent of some form to work with your project. This means that your project should expose usage information to make it easy for an agent effectively use your project.

One approach that I’ve found effective is to reference a skill.md file for the tool from the help message. For example, here’s the help output from DV Flow Manager, a workflow automation tool I work with.

usage: dfm [-h] [--log-level {NONE,INFO,DEBUG}] [-D NAME=VALUE] [-P FILE_OR_JSON]
           {graph,run,show,cache,validate,context,agent,util} ...

DV Flow Manager (dfm) - A dataflow-based build system

positional arguments:
  {graph,run,show,cache,validate,context,agent,util}
    graph               Generates the graph of a task
    run                 run a flow
    show                Display and search packages, tasks, types, and tags
    cache               Cache management commands
    validate            Validate flow.yaml/flow.dv files for errors and warnings
    context             Output comprehensive project context for LLM agent consumption
    agent               Launch an AI assistant with DV Flow context
    util                Internal utility command

For LLM agents: See the skill file at: /home/mballance/.../share/skill.md

AI agents often check a tool’s help message to better-understand its operation. Including a path to the tool’s “AI Skill” file provides the agent with a pointer to more in-depth information.

If your project produces human-consumable output, such as reports, you should have an option to produce JSON output as well. While JSON isn’t particularly easy for humans to read, agents work well with its regular structure.

Test, Test, Test

We all know that tests are good and important. But, often, we settle for a few basic tests so we can spend more time developing new features.

Here, again, AI can help. But, also, a good test suite is critical to getting good results with AI. Just like a human developer, an agent makes mistakes and a robust test suite catches those errors before they accidentally get committed.

AI and Open Source EDA Users

As an Open Source EDA user, AI provides you tools to make better use of the available software. Don’t hesitate to have your agent look at the source for software that you’re using. If you’re trying to get a case working, ask it to analyze the EDA software source alongside your code and understand what needs to change in your code.

If you hit a bug, use AI to create a reduced testcase in conjunction with the EDA software’s source.

Now, one personal request as an open source developer: please don’t just paste the AI-generated output into an Issue and click submit. The AI-created analysis is important, of course. Please include it in your Issue report. But, it’s likely that the AI-generated analysis is missing critical details about your usecase and intent. Including that critical user perspective helps to ensure that your usecase is well-supported beyond just fixing a point issue.

AI and Open Source EDA Contributors

If you’re trying to move from open source EDA user to open source EDA contributor, welcome! AI is definitely a help here as well.

Any complex codebase is difficult to get started with, and open source EDA is no different. AI offers strong benefits in helping to more-rapidly find key components of the codebase.

A key thing to bear in mind is that LLMs are tools, not oracles. Using AI isn’t going to magically turn you into an expert in a given project. And, all the best practices of contributing to an open source project still apply: ask questions, search issues, ask for feedback on contributions. That said, AI can bring you up to speed on a project far faster than you could on your own.

Set your sights a bit more broadly when it comes to reference materials. Reading an entire standard (SystemVerilog, SystemRDL, PSS) is daunting as a human, but easy with an agent. Use an agent to help explore implementation alternatives and refine requirements.

AI and Open Source EDA Sponsors

Sponsoring open source software development and maintenance has always been a bit tricky – especially for small projects. Large projects with an organization and, often, a team of paid software developers are somewhat easy: donate to the foundation, possibly participate in a steering committee, etc. In this case, there is a clear link between supporting the project financially and the project being able to scale. Smaller projects are much harder. Developers will have a ‘day job’ with contract clauses prohibiting moonlighting. But, even without this obstacle, paying the developer won’t really help the project scale because it won’t lead to more people working on the project.

While it’s still early, AI suggests a new way to support small open-source projects. AI access is typically paid by usage, coarsely denominated in Tokens. Open source developers with an effective AI utilization strategy can easily scale a project based on access to a larger number of tokens each month.

If you’re a would-be sponsor of Open Source EDA software, be on the lookout for organizations and platforms that allow you to contribute AI agent access (LLM tokens) to your favorite projects.

Conclusion

AI has the potential to scale open source EDA software efforts in ways that other technology advances simply have not. In short, allowing us as open source EDA users, contributors, and developers to focus on envisioning the workflows that we want to have, and delegating the bulk of implementation tasks to AI assistants. This new era of open source EDA promises new, more productive, approaches to silicon engineering challenges, easier-to-use tools, and new funding models to help the ecosystem scale. The future of open source EDA in the AI era is bright, and I’m excited to be here for this phase of the journey.

References

• Anthropic Skills

Example Vehicle: DMA Engine

A DMA engine is one of my favorite examples to use. It’s relatively simple, yet highlights several key aspects of a range of hardware devices:

• It is controlled via a software interface (mmio)
• It has characteristics of other bulk data movers, such as accelerators and high-speed communications interfaces
• Its operation often involves arbitration and resource contention

Let’s walk through the process of developing a series of executable and natural-language specifications that will allow us to refine a high-level natural-language specification for a DMA device to a synthesizable executable specification. I’ll store all of the models in the zuspec-example-dma repo so you can follow along if you’re interested.

DMA High-Level Specification

Let’s start with a simple natural-language spec for what we want. You can find the file here: 01_highlevel_spec.md

# DMA: High-Level Requirements

The DMA engine supports fast memory transfer between two 
memory regions. It is intended for use with both storage
and memory-mapped I/O devices.

## Transfer Requirements: General
- Each transfer shall have an associated priority (0..15)
- Each transfer shall have non-overlapping source and destination addresses
- Each transfer shall specifies the total number of bytes to transfer

## Transfer Requirements: Device
In addition to the requirements above:
- Each transfer shall specify an access size (eg 1, 2, 4, 8)
- Each transfer shall specify a chunk size, denominated in <accesses>
- The total transfer size is in bytes, and must be a multiple of <access-size>
- The source and destination addresses shall be aligned to <access-size>
- Each transfer specifies whether the source/dest addresses are incremented
- Device I/O is generally controlled by requests from the device itself
  - Request a chunk -> DMA engine performs <chunk-size> <access-size> accesses

## Transfer Requirements: Chaining
- It shall be possible to specify lists of both general and device transfers

So, these are quite high-level. They focus on the required functionality, while spending little time on how we might implement this.

Already, though, we might want to do some experiments with different executable specifications that implement the natural language one above.

DMA Algorithmic Model

Our first step is to define an algorithmic model with interfaces that satisfy the requirements above. Let’s start with the Logical Interface, since that is often how we phrase high-level requirements.

import zuspec.dataclasses as zdc
from typing import List, Protocol

@zdc.dataclass
class MemCpy(zdc.Struct):
    src: zdc.uptr = zdc.field()
    dst: zdc.uptr = zdc.field()
    sz: zdc.u32 = zdc.field()

@zdc.dataclass
class DevCpy(MemCpy):
    acc_sz: zdc.u8 = zdc.field()
    chk_sz: zdc.u32 = zdc.field()
    inc_src: bool = zdc.field()
    inc_dst: bool = zdc.field()


class DmaOp(Protocol):

    async def memcpy(
            self,
            src: zdc.uptr,
            dst: zdc.uptr,
            sz: zdc.u32,
            pri: zdc.i32 = 0):
        ...

    async def memcpy_chain(
            self,
            xfers: List[MemCpy],
            pri: zdc.i32 = 0):
        ...

    async def devcpy(
            self,
            src: zdc.uptr,
            dst: zdc.uptr,
            sz: zdc.u32,
            acc_sz: zdc.u8,
            chk_sz: zdc.u32,
            inc_src: bool,
            inc_dst: bool,
            pri: zdc.i32 = 0):
        ...

    async def devcpy_chain(
            self,
            xfers: List[DevCpy],
            pri: zdc.i32 = 0):
        ...

The API definition above captures how software would interact with the DMA engine. But, we also care about how the DMA engine accesses memory in the environment, and how devices in the environment request service from the DMA engine.

class MemoryOp(Protocol):
    """Memory interface for DMA to access system memory."""

    async def read(self, addr: zdc.u64) -> zdc.u64:
        """Read a word from memory.

        Args:
            addr: Memory address (word-aligned)

        Returns:
            Data value read
        """
        ...

    async def write(self, addr: zdc.u64, data: zdc.u64, size: zdc.i8) -> None:
        """Write a word to memory.

        Args:
            addr: Memory address (word-aligned)
            data: Data value to write
        """
        ...

mem.py defines a memory-access interface that the DMA model implementation will use to access memory in the system.

class ReqOp(Protocol):
    async def req_transfer(self, id: zdc.i32):
        """Request a transfer"""
        ...

req.py defines the API used by devices to request data transfers from the DMA engine.

In total, we’ve define the key operations used to interact with the DMA engine in less than 100 lines of code. Now, to do something with these operations.

Algorithmic Model Implementation

Now that we’ve defined our abstract interfaces, we can create an algorithmic implementation of the DMA engine.

You can find the algorithmic implementation of the DMA engine model here: op_op_alg.py.

@zdc.dataclass
class DmaOpOpAlg(DmaOp, ReqOp, zdc.Component):
    """DMA engine with no fixed channels. Uses MemoryOp for memory access
    and implements ReqOp for device transfer request control."""
    
    mem: MemoryOp = zdc.port()

The interface to the model is shown above. Because we’ve deliberately been abstract about the device’s structure – for example, how many channels it contains – the model simply implements both the DmaOp and ReqOp interfaces.

    async def memcpy(
            self,
            src: zdc.uptr,
            dst: zdc.uptr,
            sz: zdc.u32,
            pri: zdc.i32 = 0):
        """Copy memory from src to dst.
        
        Performs narrow accesses until 8-byte aligned, then wide accesses.
        """
        await self._mem_l.acquire()
        try:
            remaining = sz
            while remaining > 0:
                # Determine access size based on alignment and remaining bytes
                # Use the largest power-of-2 size that is both aligned and fits
                align = src & 0x7  # Low 3 bits give alignment
                if align == 0 and remaining >= 8:
                    xfer_sz = 8
                elif (align & 0x3) == 0 and remaining >= 4:
                    xfer_sz = 4
                elif (align & 0x1) == 0 and remaining >= 2:
                    xfer_sz = 2
                else:
                    xfer_sz = 1
                
                data = await self.mem.read(src)
                await self.mem.write(dst, data, xfer_sz)
                src += xfer_sz
                dst += xfer_sz
                remaining -= xfer_sz
        finally:
            self._mem_l.release()

The implementation of the ‘memcpy’ operation is shown above. The implementation is simple and brief, aside from a little complexity with respect to aligning the address. The total model implementation is ~150 lines of Python code, which is just about 6x the length of the original high-level spec.

Tests and Test Fixture

Now that we have a behavioral model, we need a way to exercise it. Fortunately, we have a couple of tools that simplify the process. pytest is used as the testing framework, and AI assistants are proving to be incredibly capable at creating test fixtures and tests from the behavioral model that we created.

You can find the tests in test_op_op_alg.py. The vast majority of the code was created using an AI assistant: copilot cli and Sonnet 4.5 in this case.

def test_memcpy_basic():
    """Test basic memcpy operation."""
    print("\n=== Test: Basic memcpy ===")

    @zdc.dataclass
    class Top(zdc.Component):
        fixture: DmaTestFixture = zdc.field()

        async def run(self):
            # Initialize source memory
            data = [0x10, 0x20, 0x30, 0x40]
            self.fixture.init_memory(0x1000, data)

            # Perform memcpy
            await self.fixture.dma.memcpy(
                src=0x1000,
                dst=0x2000,
                sz=32  # 4 words * 8 bytes
            )

            # Verify destination
            result = self.fixture.read_memory(0x2000, 4)
            assert result == data, f"Data mismatch: {result} != {data}"

            print("  Basic memcpy test PASSED")

    t = Top()
    asyncio.run(t.run())
    t.shutdown()

A basic transfer test is shown above, showing how the ‘memcpy’ operation is used, and how results are checked.

Conclusions and Next Steps

Engineers spend significant time working with natural-language and executable specifications. Zuspec simplifies the process of creating and testing executable specifications (models) at multiple abstraction levels, which enables greater use of executable models to help refine our natural-language specifications.

Algorithmic modeling of this style is done today – and, often, in Python. The difference with Zuspec is that the models are designed to be reusable for multiple purposes. Over the next few posts, we’ll look at how we continue to refine, reuse, and retarget our DMA model.

Resources

• zuspec-example-dma

The most difficult transition in hardware modeling is the transition from natural-language to executable specification. It is during this transition that the ambiguities inherent in natural-language descriptions are resolved. Maximizing value from a multi-abstraction hardware modeling strategy requires minimizing the number of times a natural-language spec is converted to executable. Zuspec defines interface abstraction levels that provide a basis for comparing implementations with different abstraction levels.

Connecting Modeling Abstractions

In the previous post, we looked at several internal-implementation abstraction levels. These help us explore the architecture and micro-architecture of the design with different cost and performance tradeoffs. However, the internal implementation doesn’t provide a good basis for comparing models. In essence, this means that the natural-language to executable spec translation happens for each model. This raises the cost of modeling, but also increases the risk that each model implements a slightly different interpretation of the original spec.

Ideally, we want some basis for mechanically comparing two models with different implementations such that we can easily establish whether they are equivalent according to that basis. Each model still needs to incorporate abstraction-specific details from the spec, but isn’t a full from-spec implementation.

Breaking Down Device Abstraction

Zuspec uses interface abstraction levels as this basis of comparison. The first thing to note is that there are two levels of interface: logical and physical.

The same set of interface abstractions apply to logical and physical interfaces, so let’s explore the abstraction levels first.

Abstraction: Scenario

A scenario-level interface captures rules about how a device may be used. The Portable Test and Stimulus (PSS) standard is likely the best-known example of a scenario-level interface abstraction. PSS uses scheduling rules and constraints to specify data, data-flow, and resource utilization rules. The rules of a scenario-level description assist in automating test creation and simplifying the integration of content from multiple IPs.

Abstraction: Operation

An operation-level interface captures the device interface in terms of operations that the device can perform. Think of the API of a software driver for a device. An operation-level interface lets us exercise key functions of a device without worrying too much about the details.

Abstraction: MMIO

A memory-mapped I/O (MMIO) interface uses memory-mapped registers and interrupts as the device interface.

Abstraction: TLM

A transaction-level modeling (TLM) interface uses packet-like messages. The TLM 1.0 and 2.0 standards provide good examples of this level of modeling. TLM is also heavily used in UVM testbench environments.

Abstraction: Protocol

Protocol-level interfaces are the familiar signal-level interfaces used in register-transfer level (RTL) designs.

Physical Interfaces

We’re all familiar with physical device interfaces. In RTL, these are the Protocol-level interfaces with signal-level ports at the boundary of the device. Every hardware model has physical interfaces, and these typically

Logical Interfaces

A logical interface is typically a software interface. Software, firmware, and test environments interact with a device via logical interfaces. A key attribute of a logical interface is that it is independent of the physical interface and can be virtualized.

Useful Combinations

The combination of logical and physical interface abstraction levels, combined with internal implementation abstraction level, provides a flexible way to characterize a given model. The table below summarizes how the abstraction levels apply to logical and physical interfaces.

Interface Roles

In addition to abstraction level and interface type, interface roles are also worth considering when characterizing a device.

• Initiator interfaces make requests to targets. Think: memory interface on a RISC-V core
• Target interfaces respond to requests from an initiator. Think: register interface on a UART
• Monitor interfaces passively view interaction between initiator and target

Relating Interface Abstractions

Abstractors, a term used by the IP-XACT standard, provide a mechanism for bridging abstraction levels in a reusable way. An abstractor has two or more physical interfaces with different abstraction levels and different roles. Specific kinds of abstractors often go by names like bus functional model or transactor.

With the right set of abstractors, we can provide multiple views of the same model implementation. For example, an algorithmic implementation of a device with MMIO physical interfaces can be used as a stand-in for the RTL implementation of the device with protocol-level interfaces in a verification testbench simply by adding the right protocol transactors from a library.

Next Steps

Interface abstraction levels and interface types (logical, physical) enable model reuse and provide a basis for comparing models with very different internal implementations. While there are many legal combinations of logical interface, physical interface, and internal implementation, there are a few key combinations. In the next post, we’ll start to look at how some of these key combinations, and how they are captured and evaluated in Zuspec.

A simplified silicon design process

The gantt chart above illustrates a simplified silicon design process. It deliberately makes no attempt to assign accurate relative times to any step in the process. The key challenge is that starting most steps is gated by the previous step either completing, or reaching some fairly advanced state of readiness. For example, the DV team can’t really start verifying the design until RTL is available. They can study the spec and, perhaps even, write some tests speculatively while the RTL is under development. But, validating assumptions must wait until RTL exists.

Note that these tasks are grouped by the design-model abstraction level, with most activity centering around a register-transfer-level (RTL) model of the design. This poses several challenges, but one of the biggest is that the abstraction difference between Spec and RTL is enormous.

A closer look

While the diagram above is straightforward, it hides some useful details about what is actually happening during each of the steps above.

Let’s walk through to look at the changes. First, you’ll notice that there are now four abstraction levels:

• Spec - Typically a natural-language description
• Algorithmic - A behavioral model with limited timing fidelity
• Cycle Accurate - A behavioral (non-synthesizable) model that reflects the intended micro-architecture of the design
• RTL - Synthesizable model

Spec Development

During spec development, it’s natural to use some high-level models to validate assumptions. These models are captured at a high level of abstraction, and support one of two methods of evaluation. A model intended for dynamic evaluation will be behavioral, and supports activities such as running existing software workloads. A statistical model (e.g. an Excel sheet) enables what-if analysis by adjusting control parameters. These are typically two distinct models because of the two different evaluation approaches.

RTL Implementation

The RTL development process is also not a monolith. Generally, you could think of a process by which the design is partitioned into independent sub-IP that can be implemented by different engineers. Once the design is partitioned, engineers can work in parallel to implement and test their assigned sub-IP. Finally, sub-IPs are integrated back into the overall structure of the design.

Design Verification

The design verification process is also step-wise, typically starting with basic bring-up tests to ensure that simple operations, such as register accesses, make it past the interfaces and properly interact with the design. Verification then proceeds to exercise key device usescases and, finally, exercise key implementation details.

The DV team will often create some type of reference model or predictor to use in checking results from the design. Sometimes this will be cycle accurate, but it might also be at an algorithmic level of abstraction.

Looking in more detail, it becomes clear that modeling at different abstarction levels is being done. But, too often, these models are only used within a specific silo. There are many reasons for this, including the language(s) used to implement models and integration challenges.

Shifting Left with Model Reuse

The Zuspec ‘bet’ is that we can reorganize the silicon development process by making models easier to create, easier to reuse and transform, and easier to integrate. Future posts will go into more depth on how Zuspec enables this. For now, let’s look at how different modeling abstractions are used across the silicon development process.

Let’s look at some of the key points:

• A single algorithmic model is used to serve both dynamic (simulation) and static/formal evaluation during the spec development process.
  • The DV team can use this algorithmic model, with a few modifications, as a substitute for RTL while they setup the testbench environment and write tests that exercise the specified design behavior.
  • The Firmware team can also get started writing firmware using the algorithmic model.
• The RTL implementation team develops a cycle-accurate model of the design as part of the process of partitioning the design.
  • The RTL implementation team selectively replaces sub-IPs within the cycle-accurate model to test a particular sub-IP’s implementation together with the more-abstract remainder of the design model.
  • The DV team can move to running their tests against the more-accurate model. This helps to highlight different interpretations of the spec much earlier.
  • The DV team can also run their tests against various configurations of the hybrid cycle accurate / RTL model of the device to begin exercising sub-IPs prior to availability of the fully-integrated RTL. Doing this can also enable tests that target implementation coverage to be developed incrementally as the relevant sub-IPs are ready.
• Once the RTL is ready, the DV team proceeds to run bring-up activities. Final issues are much easier to track down because the tests are known to run against the cycle-accurate model and various combinations of RTL sub-IPs.

So, how much time will we save? That, of course, heavily depends on the relative size of the tasks shown above, as well as on the cost of creating the set of models used above. But, the savings should be significant.

Next Stes

We’ve looked at several implementation abstraction levels for device models. In the next post, we’ll dig into interface abstraction levels and see how these enable incremental refinement of models.

DSL or Class Library?

In my experience, the use of hardware modeling varies widely across project teams. At the extremes, some attempt to maintain a consistent set of models across various abstraction levels, while others focus on producing RTL for their piece of the design and create models on an as-needed basis to achieve that task. While these approaches seem very different there are points of intersection. For example, both teams will likely have a predictor model for use in verification. Both teams will likely find that model creation is time consuming and, depending on their choice of modeling language, both may have challenges integrating a predictor model into their verification environment.

Modeling language is one of the first choices to be made when creating a hardware model. In general, there are two choices: select a domain-specific language such as SystemVerilog, or select a class library, such as SystemC, that is implemented in terms of a general-purpose language.

Both of these approaches have benefits and drawbacks.

Benefits

• Language
  • Full flexibility to have domain-specific features
  • Clear boundaries between what is the ‘language’ and the rest of the
  • Full flexibility to process a model
• Class Library
  • Leverage existing tools (compilers, editors, linters, debuggers) for the base language
  • Leverage existing expertise in the base language
  • Easily expand the class library to add new capabilities

Drawbacks

• Language
  • Expensive to implement and add new features
  • Must convince users to learn and become proficient in the language
  • Interoperability with existing languages and tools can be a challenge
• Class Library
  • Existing tools don’t comprehend domain-specifics encoded by the library
  • The need to work with base-language compilers limits how the model can be processed
  • The base language often limits how easily/naturally domain-specific features can be described

We currently use a variety of domain-specific languages across the design and verification process. Ideally, we could apply a modeling approach that retains the key benefits of both approaches much more broadly.

Zuspec: A DSL / Class Library Hybrid

Zuspec is a Python class library with a twist. A model described with Zuspec dataclasses is completely valid Python syntax, and can be validated with existing Python static checkers. But, due to some key Python capabilities, a Zuspec model can also be processed as if it were a domain-specific language.

Python offers benefits both to the Zuspec users (ie the author of a Zuspec model) and to tool implementors. For users, large portions of the existing tool ecosystem can be leveraged natively with a Zuspec description. Because the Zuspec library adheres to Python type rules, content-assist and navigation features in integrated developement environments, such as VSCode, work properly. For the same reason, static type checkers can help detect issues, such as incorrect use of functions, early.

But, what’s even more attractive about Python is that it provides parsing infrastructure that helps Zuspec construct an intermediate-representation (IR) data model that captures details that would impossible for a pure class library to capture. This IR also allows Zuspec to map a Zuspec model to a variety of implementations.

Let’s look at a simple example:

    @zdc.dataclass
    class Prod(zdc.Component):
        p : zdc.PutIF[int] = zdc.port()

        async def _send(self):
            for i in range(16):
                await self.p.put(i)
                await self.wait(zdc.Time.ns(10))

    @zdc.dataclass
    class Cons(zdc.Component):
        c : zdc.GetIF[int] = zdc.port()

        @zdc.process
        async def _recv(self):
            while True:
                i = await self.c.get()
                print("Received %d" % i)

    @zdc.dataclass
    class Top(zdc.Component):
        p : Prod = zdc.inst()
        c : Cons = zdc.inst()
        ch : zdc.Channel[int] = zdc.inst()

        def __bind__(self): return (
            (self.p.p, self.ch.put),
            (self.c.c, self.ch.get)
        )

    t = Top()

    asyncio.run(t.p._send())

This is a simple producer-consumer model. The producer and consumer communicate via a channel, and the testbench is responsible for activating the producer. As a side-note, a comparable case in SystemC is roughly twice as many lines of code, so there are already some measurable efficiencies.

Staying inside Python early in the model-development process is attractive due to the fast turnaround time and access to existing Python libraries. Any Zuspec model can be run directly in Python and can access all Python language and library features.

If you look closely at the description above, you might find yourself wondering how it executes. For example, how are ports connected? This is where some of the ‘declarative’ aspects of this description come into play. Despite the description looking and behaving like a class library, there is still some “magic” behind the scenes. In the case of port connections, the Zuspec library takes the user’s bind specification and determines how to properly connect ports and channels. And, of course, there are many other cases where Zuspec allows the user to specify what is desired and have the library determine how that intent is implemented.

Beyond Pure Python

There are quite a few projects that seek to translate Python to a more-performant implementation. Python ahead-of-time (AOT) compilers typically work with a Python script (and it dependent libraries) as a whole. Zuspec looks at the world differently.

Identifying the Model Boundary

Zuspec uses types defined in zuspec.dataclasses to identify the boundary of a model. For example, in the example above, the ‘Top’ class defines such a boundary. Tools that map a Zuspec description to a non-Python implementation operate on such boundaries.

Pure Python vs Retargetable

The other place where Zuspec is a bit different is in defining ‘Profiles’ for content. This has significant similarities to the SystemVerilog “synthesizable” subset. The first choice is whether a model is Retargetable or not. Retargetable models can be mapped to non-Python implementations.

In order to be retargetable, a model can only contain elements of Zuspec-recognized types. The ‘Top’ class above matches this criteria. That said, as long as running in Python is sufficient, a Zuspec model is free to use any Python construct.

Checking Profile compliance is another place where the Python ecosystem helps. Zuspec implements a plug-in to the flake8 linter that allows Zuspec to check profile compliance along with other Python rules that flake8 checks. This allows Zuspec-specific checks to be performed on-the-fly as code is developed, providing much faster feedback to the developer (or LLM, as is often the case today).

The diagram above shows several options for how a Retargetable Zuspec model might be implemented. Several of these targets, such as SystemVerilog RTL, have their own Profile that further restricts available features.

Conclusions and Next Steps

Zuspec is showing early promise in simplifying hardware model creation, and allowing those models to be reused and retargeted to a variety of environments. Next time, we’ll look at modeling abstraction-level methodology, and how this helps humans (and LLMs) to more-effectively discuss and implement the hardware models they care about.

References

• Zuspec: Pythonic Model-Driven Hardware Development

The Value of Consistency

There has always been significant cross-over between open source and closed-source development in the software world. Students and hobbyists gain critical skills working with open-source tools, with the understanding that the same languages, methodologies, and tools are used in environments where the work product may not be open source. Companies that produce closed-source software often contribute to open-source libraries and tools that they use internally, and benefit from a larger community of users and developers.

By and large, this holds true in the FOSSi community when it comes to hardware design. SystemVerilog and VHDL are used to capture hardware designs, with full open- and closed-source tool stacks to simulate and synthesize. Innovative methodologies and tools, such as CHISEL and Amaranth HDL, increase productivity while still connecting to existing tools using standard hardware description languages (HDLs).

Support for standard languages and a standard design methodology has been critical in fostering a sizable ecosystem of available and reusable open-source hardware designs. Because these open-source hardware components use the same standard interchange formats used for closed-source development, the technical aspects of integrating an open-source component into a closed-source design are straightforward.

FOSSi and Functional Verification

Until recently, the picture was quite different for functional verification. Functional verification is the systematic process of confirming that the implementation of a hardware design matches the intended functionality, as described by the functional specification. Due to tool capabilities, what is common when developing with closed-source tools differs significantly from what is common when developing with open-source tools.

Across the industry, SystemVerilog/UVM is the most-prevalent infrastructure used to create verification environments. Until recently, only closed-source tools could run SystemVerilog/UVM testbench environments. Thus, content intended to run with a pure open-source tool stack had to use a different testbench methodology.

Toward a Portable Verification Methodology

Ideally, as a community, we can have the best of both worlds: the ability to use prevalent industry libraries and methodologies with open- and closed-source tool chains, and the ability to add new technologies and techniques on top.

A portable verification stack allows students and hobbyists to hone their skills in dominant industry practices, while also enabling them to explore emerging new verification approaches and technologies. A portable verification stack also makes it easier for industrial users to incorporate new technologies into their existing SystemVerilog/UVM environments.

Leveraging SV/UVM in a portable verification flow has other highly-desirable side effects as well. Having more open-source verification collateral written in SystemVerilog will help to increase Verilator’s support for the language, and will result in increased testing of Verilator due to the prevalence of continuous-integration flows used for open source.

Why Focus on Verification IP?

Protocol Verification IP (VIP) is the nexus of the various flows shown above for good reason. Hardware designs interact with the outside world via their interfaces. Using standard interfaces vastly simplifies the task of integrating designs. Standard interface protocols range from quite simple to incredibly complex. Most importantly, the most critical aspects to verify in a hardware design are typically not the implementation of the interface protocols. And, what’s more, the way our tests wish to interact with the design is typically at the software level – for example, memory reads and writes – not at the detailed level of the interface protocol.

That’s where protocol Verification IP comes into the picture. Just like other reusable design IP, protocol verification IPs are pre-verified components of the testbench environment that exist to translate between the software-level activity of our tests and the detailed signal-level implementation of a standard protocol.

Verification IP allow us to start testing the unique aspects of our design more quickly, since we can interact with the ‘test’ side of the VIP at a high level, with confidence that the VIP will translate to the details of the standard protocol. Being able to use UVM in our verification flow gives us access to a much wider set of reusable verification IP.

Conclusion

Support for SystemVerilog/UVM in open-source tools opens up new possibilities for sharing within the FOSSi community and with the closed-source silicon development industry. It allows students and professional hobbyists to hone their skills with common industrial practice using open source tools and collateral. And, it enables far better distributed development by allowing all contributors to access the same continuous integration (CI) flow.

We’ll look at an architecture for modular multi-language/multi-environment UVM protocol VIP in a future series of posts. But, next week, we’ll spend some time looking at the suite of PyHDL-IF examples and how to run them.

References

• Support for upstream UVM 2017 in Verilator
• CHISEL
• Amaranth HDL
• 2024 Wilson Research Group Functional Verification Study
• Verilator
• UVM

Feeding Python Development Tools

Python has a rich ecosystem of developer tools. There are IDE plug-ins that assist developers in navigating around a codebase, and provide context-aware editing capabilities. There are static-checking tools (MyPy, Flake8, etc) that identify coding mistakes before execution, saving iteration time. And, of course, there are a collection of AI assistants (Copilot, Cline, Codex, Claude, etc) that have proven very adept at writing Python code. The common factor with all of these tools is that they all operate on Python source.

We’ve gotten this far without needing to generate any testbench-specific Python or SystemVerilog code to implement a general-purpose Python integration with a UVM testbench. Fortunately, the same dynamically-discovered data that enables ease of integration can be used to generate the Python source that enables our development tools.

Discovering Available Types

PyHDL-IF already uses the vast majority of the data required to generate a Python view of user-defined SV/UVM classes to implement the runtime integration between Python and SystemVerilog – specifically, identifying and accessing named component instances and fields registered with the UVM library. The one piece that we’re missing is a list of all the classes registered with the UVM factory.

Unfortunately, the UVM library doesn’t make this information available via a standard API. The good news is that there is a workaround. The UVM factory provides a print function that reports the names of registered classes via the UVM report infrastructure. Using a custom message handler, we can intercept and save this catalog of available choices. You can find the relevant code in src/hdl_if/share/uvm/pyhdl_uvm_object_rgy.svh.

/** 
 * Implements a report catcher to allow capturing the 
 * list of object typenames printed by the factory
 */     
class factory_print_catcher extends uvm_report_catcher;
    string  factory_print;

    function new(string name="factory_print_catcher");
        super.new(name);
    endfunction

    function action_e catch();
        factory_print = get_message();

        // Suppress the message
        return CAUGHT;
    endfunction
endclass

class pyhdl_uvm_object_rgy;
    // ...
    virtual function string _get_type_dump();
        factory_print_catcher catcher = new;
        uvm_factory factory = uvm_factory::get();

        // Attach our custom report catcher so we can 
        // save the message printed by factory.print()
        uvm_report_cb::add(null, catcher);

        factory.print();

        uvm_report_cb::delete(null, catcher);

        return catcher.factory_print;
    endfunction

    // ...
endclass

The pyhdl_uvm_pygen UVM Test

We need to run the simulator in order to load and execute code from the UVM testbench. In a UVM environment, the UVM test is the center of executing test behavior, so it makes sense to provide a UVM test that handles discovering the available user-defined UVM classes and generating a Python view. The PyHDL-IF library provides the pyhdl_uvm_pygen test for this purpose.

While the pyhdl_uvm_pygen test is the entrypoint, the task of discovering available classes, processing them, and generating Python is all implemented in Python.

Example

While all the details of how we extract information from SV/UVM classes is interesting, pragmatic users will be much more interested in applying the workflow and using the result.

Let’s look at an example, which you can find in examples/uvm/pygen.

This example consists of a simple UVM environment with a memory-oriented sequence item, shown below:

    class seq_item extends uvm_sequence_item;
        bit              ctrl_addr_page;
        bit[1:0]         addr_page;

        rand bit [7:0]   addr;
        rand bit         write; // 1=write, 0=read
        rand bit [31:0]  data;
        rand bit [3:0]   tid;

        // ...

        `uvm_object_utils_begin(seq_item)
            `uvm_field_int(ctrl_addr_page, UVM_ALL_ON)
            `uvm_field_int(addr_page, UVM_ALL_ON)
            `uvm_field_int(addr , UVM_ALL_ON)
            `uvm_field_int(write, UVM_ALL_ON)
            `uvm_field_int(data , UVM_ALL_ON)
            `uvm_field_int(tid  , UVM_ALL_ON)
        `uvm_object_utils_end

        // ...
    endclass

Our build/run-flow specification (flow.yaml) specifies how to build and run tests. This example also launches the PyHDL-IF-provided UVM test that generates Python classes. Note how the task parameters specify a SystemVerilog plusarg (+pyhdl.outdir) to specify the destination directory for the generated Python classes.

  - name: sim-run
    uses: "hdlsim.$.SimRun"
    needs:
    - sim-img
    - pyhdl-if.DpiLib
    with:
      plusargs:
      - UVM_TESTNAME=pyhdl_uvm_pygen
      - pyhdl.python=$/../../packages/python/bin/python
      - pyhdl.debug=0
      - pygen.debug=1
      - pyhdl.outdir=$/env_classes/env

Running the sim-run task runs the pyhdl_uvm_pygen UVM test, which generates Python classes in the example directory. The class corresponding to the sequence item is shown below. You can find the full code in examples/uvm/pygen/env_classes/env/seq_item.py.

@dc.dataclass(kw_only=True)
class seq_item_fields(object):
    ctrl_addr_page : int = dc.field(default=0)
    addr_page : int = dc.field(default=0)
    addr : int = dc.field(default=0)
    write : int = dc.field(default=0)
    data : int = dc.field(default=0)
    tid : int = dc.field(default=0)

@dc.dataclass
class seq_item(uvm_object, seq_item_fields):
    pass

The class fields are declared in a pure-data class (seq_item_fields) to make it easier to use just the data aspect of the class for unit testing.

Once generated, these Python classes that mirror the user-defined SystemVerilog/UVM classes can be supplied to all of our standard Python development tools, allowing these tools to check and provide help working with the Python interface to our SystemVerilog/UVM testbench.

Conclusion

The PyHDL-IF library provides an easy-to-use integration between Python and a SystemVerilog/UVM testbench environment. And, by generating a Python view of the SystemVerilog classes, supports Python development tools in providing a productive developer experience.

We’ll look at other features of the PyHDL-IF library and its support for SV/UVM in future posts. But, more immediately, we’ll be looking at how recent changes in the open-source EDA ecosystem are changing what’s possible in a verification flow that supports both open-source and closed-source tools.

References

• PyHDL-IF
• MyPy
• Flake8

Working with Analysis Ports

UVM testbench environments use analysis ports extensively. An analysis port publishes data to zero or more listeners, and is used to route transactions from interface monitors to scoreboards and other analysis components.

Connecting to analysis ports from Python allows scoreboards and other analysis components to be implemented in Python. There are two technical requirements that enable Python to receive transactions published by analysis ports:

• Be able to identify a uvm_analysis_port as a distinct type (vs, say, a uvm_object or uvm_component).
• Be able to add a new listener to the analysis port

Challenges of Dynamically Using Analysis Ports

Each of these technical requirements poses its own challenge.

SystemVerilog is a statically-typed language that provides minimal introspection tools for looking at the internals of user-defined classes. This is especially true when it comes to templated types. In order to ask whether a given object is an instance of uvm_analysis_port, we need to ask about a specific specialization of that type – for example, “uvm_analysis_port #(my_special_transaction)”. As you might expect, this poses some challenges because the PyHDL-IF library only knows about concrete types defined by the UVM library, and doesn’t know anything about the transaction types used within a user’s testbench. As a consequence, when the PyHDL-IF library looks at an analysis port instance, it just sees a uvm_component instance.

One possible approach to this challenge is to have the user register each of the transaction types that they might want to use with analysis ports with the PyHDL-IF library. For example:

class my_transaction extends uvm_sequence_item;
  // ...
endclass

`pyhdl_uvm_transaction_utils(my_transaction)

This would allow the PyHDL-IF library to identify analysis-port instances, but wouldn’t help with the second challenge of working with analysis ports.

The second challenge comes when we want to add a new listener to an analysis port. This must be done during connect_phase, and requires that a properly-specialized uvm_analysis_imp #(T) class instance was previously created during the build phase.

Making Analysis Ports Visibile

While both of these challenges can be overcome independently, doing so would require the user to make two independent sets of changes. And, more troubling, wouldn’t provide a good way for VIP developers to hide this complexity from users. At minimum, the testbench developer would always need to pre-create uvm_analysis_imp instances for each analysis port to which they might subscribe.

Instead, PyHDL-IF provides two classes that supports two paths for making analysis ports visible and accessible from Python:

• pyhdl_uvm_analysis_port – An alternative analysis port implementation intended for use by VIP authors
• pyhdl_uvm_analysis_imp – An analysis port listener intended to make existing analysis ports available to PyHDL-IF

Example

Let’s take a look at an example to understand how analysis ports are made accessible to the PyHDL-IF library. The uvm/seq_item_scoreboard example shows how to make analysis ports accessible as well as how to receive transactions from analysis ports.

  // Producer component with two analysis ports
  class dual_producer extends uvm_component;
    `uvm_component_utils(dual_producer)

    pyhdl_uvm_analysis_port #(seq_item_a) ap_a;
    uvm_analysis_port #(seq_item_b) ap_b;

    function new(string name, uvm_component parent);
      super.new(name, parent);
    endfunction

    function void build_phase(uvm_phase phase);
      super.build_phase(phase);
      ap_a = new("ap_a", this);
      ap_b = new("ap_b", this);
    endfunction

The code snippet above shows how the pyhdl_uvm_analysis_port can be used instead of uvm_analysis_port to make an analysis port available to the PyHDL-IF library. The API of this class is identical to uvm_analysis_port, making this a good choice for VIP authors that want to automatically make analysis ports accessible.

  // Environment tying producer to scoreboard
  class my_env extends uvm_env;
    `uvm_component_utils(my_env)

    // ...
    pyhdl_uvm_analysis_imp #(seq_item_b)    ap_b_proxy;
    // ...

    function void build_phase(uvm_phase phase);
      super.build_phase(phase);
      // ...
      ap_b_proxy = new("ap_b_proxy", this);
    endfunction

    function void connect_phase(uvm_phase phase);
      super.connect_phase(phase);
      // ...
      prod.ap_b.connect(ap_b_proxy.analysis_export);
    endfunction
  endclass

Note that ap_b uses a normal uvm_analysis_port in the VIP. We can make this analysis port accessible to the PyHDL-IF library by connecting an instance of pyhdl_uvm_analysis_imp to it. While this could be done anywhere, it’s often done in the environment (as shown above).

The pyhdl_uvm_analysis_imp instance is connected to the analysis port in the same way that any other analysis port subscriber does. Doing this allows Python code to receive transactions published by the analysis port.

Both pyhdl_uvm_analysis_port and pyhdl_uvm_analysis_imp have a proxy field inside with a add_listener method that the Python environment uses to register a listener. Let’s look at the Python environment now.

class PyComp(uvm_component_impl):

    def build_phase(self, phase):
        print("build_phase", flush=True)

    def connect_phase(self, phase):
        print("connect_phase", flush=True)
        env = self.proxy.get_parent()
        env.prod.ap_a.proxy.add_listener(self.write_a)
        env.ap_b_proxy.proxy.add_listener(self.write_b)

    def write_a(self, t):
        print("write_a %0s" % str(t.pack()), flush=True)

    def write_b(self, t):
        print("write_b %0s" % str(t.pack()), flush=True)

In this case, the component proxy is a child instance of the env class shown above. Consequently, to connect to the analysis ports, we first need to get a handle to the instance of the env class (our parent). After that, we need to access the analysis port proxy field inside the pyhdl_uvm_analysis_port and pyhdl_uvm_analysis_imp instances. We can pass any callable Python method or object to the add_listener method. In this case, we simply register two class methods. When simulation runs, write_a and write_b will be called whenever the analysis port that they monitor publishes a transaction.

Conclusions and Next Steps

The PyHDL-IF library allows analysis ports to be made visible and accessible from Python with a small one-time investment. Verification IP (VIP) developers can implement this support, allowing all users to benefit. Testbench developers can also perform this work for VIP that isn’t pre-instrumented. The result is that scoreboards and other analysis components can easily be developed in Python.

Thus far in the series, we’ve seen how to run Python behavior from SystemVerilog. We’ve seen how to interact with user-defined UVM class fields, and we’ve now seen how to subscribe to analysis ports. These technical capabilities make it easy for Python to dynamically interoperate with an existing SystemVerilog/UVM testbench. But, thus far, these capabilities don’t do much to support Python development tools. In the next post, we’ll see how the PyHDL-IF library provides a bridge from SystemVerilog/UVM to help Python development tools understand what is present in the UVM environment and make us more productive developing Python testbench components.

References

• PyHDL-IF library - https://github.com/fvutils/pyhdl-if
• Analysis port example - https://github.com/fvutils/pyhdl-if/tree/main/examples/uvm/seq_item_scoreboard

Two Kinds of User-Defined Data

There are two key kinds of user-defined data that we care about in our UVM environment: named UVM instances, and data fields. In both of these cases, a SystemVerilog environment typically references the named field directly.

    task body();
      uvm_status_e   status;
      uvm_reg_data_t rd;

      // Program CTRL / CLKDIV / SS
      m_env.m_reg.CTRL.enable.write(status, 1);
      m_env.m_reg.CTRL.master.write(status, 1);
      m_env.m_reg.CLKDIV.div.write(status, 16'h0004);
      m_env.m_reg.SS.ss_mask.write(status, 4'h1);

      // ...
    endtask

An example of using named instance fields, using registers, is shown above. Our goal is to be able to access these fields just as easily in Python, as well as plain data fields.

Named UVM Instances

Named UVM instances are UVM objects registered with the UVM library using a name. User code typically accesses these objects via the SystemVerilog instance fields, but they can also be obtained using UVM API methods. Fortunately, Python provides specific functionality to enable us to do this.

  class spi_reg_block extends uvm_reg_block;
    `uvm_object_utils(spi_reg_block)

    rand reg_CTRL   CTRL;
    rand reg_STATUS STATUS;
    // ...

    function new(string name="spi_reg_block");
      super.new(name, UVM_NO_COVERAGE);
    endfunction

    virtual function void build();
      // ...

      CTRL   = reg_CTRL  ::type_id::create("CTRL");
      STATUS = reg_STATUS::type_id::create("STATUS");
      // ...

      CTRL  .configure(this, null, "");
      STATUS.configure(this, null, "");
      // ...
    endfunction

  endclass

Registers and register fields provide a good example of UVM named instances. As shown above, register blocks (and registers) usually provide named SystemVerilog fields to represent registers and fields. But, the configure method also registers the object with the UVM API such that it can be found by name. In the case of the register block, the get_registers function returns a list of register objects.

The Python __getattr__ method allows us to access UVM named instances from Python just as easily as in SystemVerilog.

@api
class uvm_reg_block(uvm_object):

    def __init__(self):
        self._reg_m = None

    # ...
    @imp
    def get_registers(self) -> List[uvm_reg_p]:
        raise NotImplementedError()
    
    def __getattr__(self, name):
        if self._reg_m is None:
            regs = self.get_registers()
            self._reg_m = {}
            for r in regs:
                self._reg_m[r.get_name()] = r
        if name in self._reg_m.keys():
            return self._reg_m[name]
        else:
            raise AttributeError("No register %s in block %s" % (
                name, self.get_name()))

The Python code snippet above shows how this is implemented for the uvm_reg_block class. Python calls the __getattr__ class method any time an unknown class attribute is referenced. In a uvm_reg_block class, we build a map of the named register fields and return the proper one if it is available.

class PyRegSeq(uvm_sequence_impl):

    async def body(self):
        # Obtain the register model from the sequencer
        seqr = self.proxy.m_sequencer
        _,spi_regs = seqr.get_config_object("spi_regs", False)

        print("spi_regs: %s" % str(spi_regs), flush=True)

        spi_regs.CTRL.enable.set(1)
        spi_regs.CTRL.master.set(1)
        await spi_regs.CTRL.update()

        spi_regs.CLKDIV.div.set(0x4)
        spi_regs.SS.ss_mask.set(0x1)
        await spi_regs.CLKDIV.update()
        await spi_regs.SS.update()

        await spi_regs.TXDATA.write(0xA5)

Connecting __getattr__ to a search of named UVM fields enables a Python-implemented UVM sequence to access registers and register fields directly, as shown above.

Plain-Data Fields

Accessing UVM named-instance fields is useful in some cases, but there are many other cases where the fields are not named instances. UVM sequence-item fields are a great example. Python code may wish to both read and write the value of these fields. While the path to accessing the value of these fields is a bit less direct, UVM absolutely provides a path for doing so.

class seq_item extends uvm_sequence_item;
    bit              ctrl_addr_page;
    bit[1:0]         addr_page;

    rand bit [7:0]   addr;
    rand bit         write; // 1=write, 0=read
    rand bit [31:0]  data;
    rand bit [3:0]   tid;

    // ...

    `uvm_object_utils_begin(seq_item)
        `uvm_field_int(ctrl_addr_page, UVM_ALL_ON)
        `uvm_field_int(addr_page, UVM_ALL_ON)
        `uvm_field_int(addr , UVM_ALL_ON)
        `uvm_field_int(write, UVM_ALL_ON)
        `uvm_field_int(data , UVM_ALL_ON)
        `uvm_field_int(tid  , UVM_ALL_ON)
    `uvm_object_utils_end
    // ...
endclass

The code snippet above shows a typical UVM sequence item with random fields. This sequence item uses the UVM field macros (eg uvm_field_int) to register the user-defined fields with the UVM library. This enables the UVM library to automatically implement several pieces of functionality, such as comparing the value of two objects and copying the field values of an object. Users can also implement these functions by hand-implementing methods such as do_copy and do_compare, but that results in quite a bit of hand-created code and an increased risk of introducing errors.

There are three key elements of functionality that the PyHDL-IF library uses to enable user-defined data fields to be accessed from Python:

• sprint – Converts the class and its fields to a string representation
• pack_int – Packs the field values to an array of unsigned ints
• unpack_int – Sets the field values from an array of unsigned ints

Used together, these three methods provide the PyHDL-IF library everything it needs to allow Python to easily get and set the value of user-defined fields. If you’re interested in the details of how it works, see the mk method of the uvm_object_rgy class.

The short version is that type information is built each time a new type of UVM object is passed from SystemVerilog to Python. The field names and types are extracted using the string representation provided by sprint. The field names and types are used to dynamically define a Python type. When Python code calls the pack method, an instance of this Python type is constructed with field values provided by packing the SystemVerilog field values. Setting the value of the SystemVerilog fields is done by calling unpack in Python. Let’s see how it is used.

class PyRandSeq(uvm_sequence_impl):
    async def body(self):
        # ...

        # Now, exercise each page in turn 
        for i in range(4):
            req = self.proxy.create_req()
            
            # Get the current values
            val = req.pack()
            val.ctrl_addr_page = 1
            val.addr_page = i

            # Set the field values
            req.unpack(val)

            await self.proxy.start_item(req)
            # Randomize with control knobs
            req.randomize()
            await self.proxy.finish_item(req)

The example above shows how to use both the pack and unpack methods to control randomization from Python using randomization control knobs. In this case, we want to control the address “page” – its upper bits. To do this, the sequence creates an instance of the request object, then calls pack to obtain a Python object containing the field values of the SystemVerilog sequence item. After setting the desired address page, the unpack method is called to set the value of the SystemVerilog fields. Finally, the standard start_item, randomize, finish_item sequence of calls is made to execute the sequence item on the driver.

Conclusion

The PyHDL-IF library allows Python code to easily access both named UVM instance fields and data fields. This significantly enhances the type of test and analysis behavior that can easily be implemented in Python.

Thus far in this series of posts, we’ve seen how to launch Python behavior from SystemVerilog, interact with UVM APIs, and access fields declared in SystemVerilog UVM classes. Next, we’ll take a look at UVM analysis ports. Analysis ports are critical for obtaining transactions for scoreboards and other analysis components. Working with them in a generic fashion is tricky. Next time, we’ll see how the PyHDL-IF library makes them easily accessible from Python.

References

• PyHDL-IF library: https://github.com/fvutils/pyhdl-if
• Example: spi_reg_seq: https://github.com/fvutils/pyhdl-if/tree/main/examples/uvm/spi_reg_seq
• Example: sequence-item knobs: https://github.com/fvutils/pyhdl-if/tree/main/examples/uvm/sequence_item_knobs