Topwrap 0.7.0: improved YAML syntax with initial clock and reset support, extended SystemVerilog parsing, and more

Topwrap, Antmicro’s open source framework for ASIC/FPGA design aggregation first introduced in 2024, is being continuously improved to provide a standardized approach for organizing digital design blocks (often called IPs) into various configurations, making top-level designs easier to process automatically.

In our previous blog, we covered a range of functional enhancements aimed at simplifying digital design such as the introduction of automatic design validation, a SystemVerilog frontend or support for new bus interfaces. Since then, we’ve been actively working to make the Topwrap user experience scale better between simpler and more complex designs via CLI-level configurations as well as drag-and-drop interactions in the GUI.

The latest 0.7.0 Topwrap release brings optimized component-based YAML file syntax, the ability to parse hierarchical SystemVerilog designs into diagrams, and further GUI updates. In this article, we provide a detailed overview of the changes and demonstrate how they can help you aggregate your SoC components into a structured codebase that can be further processed and maintained throughout the entire design lifecycle with a unified toolkit.

Optimized YAML structure

The new, optimized structure of Topwrap YAML files focuses on even more modularity and simple, concise design description. This section showcases some of the changes introduced in the new release, but you can also follow the (updated) detailed step-by-step instructions on how to design SoCs in Topwrap from the ground up by visiting our getting started guide.

As part of Topwrap’s YAML improvements, we’ve moved some key design fields (e.g. ports, interfaces) along with name, hierarchies and interconnects to the top-level of the YAML file. In a similar manner, IP core parameters can be defined in the IP instantiations. You can also find all connections grouped in a separate dedicated section, and their values can be (bit-wise) inverted by prepending the ~ (tilde) symbol to the signal being assigned, which provides a convenient way to connect signals of negated polarity.

Here’s a sample YAML file featuring these updates:

name: demo_soc

ips:
  vexriscv:
    file: repo[demo_repo]:VexRiscv
  wb_ram:
    file: repo[demo_repo]:mem
    parameters:
      depth: 0x1000
      memfile: '"build/mem.init"'
  wb_uart:
    file: repo[demo_repo]:wb_uart

connections:
  ports:
    vexriscv:
      externalResetVector: 0x10000000
      externalInterruptArray: ~[wb_uart, irq]
    wb_uart:
      serial1_tx: tx
      serial1_rx: rx

external:
  ports:
    in:
      - clk
      - rst
      - rx
    out:
      - tx

Starting from Topwrap 0.7.0, you can easily define subordinate interfaces via memory maps, specifically in simple hardware designs where interface names can be fully omitted if they’re unambiguous. Additionally, you can attach sizes to interfaces in IP cores to prevent duplication when using the same IP many times. As you can see in the example below, wb_uart doesn’t need to specify the size: 0x1000 explicitly:

interconnects:
  wishbone_interconnect:
    clock: clk
    reset: rst
    type: Wishbone Round-Robin
    params:
      addr_width: 30
      data_width: 32
      granularity: 8
      features: ['CTI', 'BTE', 'ERR']
    memory_map: mmap1
    managers:
      vexriscv:
        - ibus_wb
        - dbus_wb

memory_maps:
  mmap1:
    wb_uart:
      address: 0xF0000000
    wb_ram:
      address: 0x10000000
      size: 0x1000

One more update worth noting is the ability to assign default values to ports in IP core YAML files, which allows setting sensible defaults and tie-offs for input ports that would otherwise need to be explicitly listed in the design description.

Initial support for clock and reset domains

As part of the YAML syntax updates, we have also introduced initial support for clock and reset domains that enables automatic wiring of clock and reset signals and allows for permorming basic sanity checks for interface connections, making sure that both sides are within the same clock domain.

Clock and reset domains are defined in the design description file, where a signal is associated with a name and corresponding properties (e.g. reset polarity). When adding IP cores to a design, its clock and reset inputs can be assigned to domains. For simple cases, the assignments can be omitted and inputs will be assigned to the corresponding default domain.

clock_domains:
  default:
    signal: clk
  i3c:
    signal: i3c_clk

reset_domains:
  default:
    signal: rst
    polarity: active high
    synchronous_to: default

ips:
  i3c_core:
    ...
    clocks:
      core: default
      phy: i3c

As visible from the example above, a simplified clock and reset wiring mechanism allows for a better and more convenient way to define, inspect, and validate connections directly in the YAML file.

Extended SystemVerilog parsing and better design representation in the GUI

Building on our previous work on improving SystemVerilog support in Topwrap, we have extended the SystemVerilog frontend to parse and visualize existing hierarchical SystemVerilog designs, so that after the hierarchy is displayed it’s easier to reason about the architecture of the analyzed IP. The arbitrary logic that lies between modules is reflected as black box modules.

Block diagrams of external projects can also be visually represented in Topwrap’s interface, currently accessible only in the read-only mode. The mechanism of changing the layer visibility in the Settings provides a quick way to adjust the represented granularity and complexity of a design, which you can test using an interactive data flow diagram, represented in the Topwrap’s GUI:

For a more complex data flow example, check the parsed design of the Caliptra UART available in the documentation.

Upcoming: Renode simulator integration and IP-XACT standard support

An interesting development that is currently underway is Topwrap’s integration with our open source Renode framework for simulation and software development. With the upcoming Renode plugin, Topwrap will be able to automatically generate Renode platform descriptions (REPL files) from the same YAML-based SoC specification that’s used to generate hardware. Because Topwrap description already contains the complete system architecture, it can serve as a single source of truth for both RTL and emulation, which will allow generating a matching Renode platform alongside the Verilog design. With Renode co-simulation and features such as trace-based modelling, SoC developers gain additional insight that support architectural decisions and help quickly evaluate changes or additions to the design.

Another planned addition is support for the IP-XACT standard that will allow Topwrap to integrate more easily with existing SoC design flows and EDA toolchains. By importing and exporting IP-XACT descriptions, Topwrap will be able to interoperate with third-party IP catalogs and tools while preserving its YAML-based design methodology.

We also plan to introduce an architecture flow that will help users define IP blocks and assemble complete SoCs entirely through the GUI, making Topwrap particularly well-suited for rapid architectural exploration and early-stage SoC design.

Leverage Topwrap for faster, more convenient work on SoC designs

Antmicro continuously expands Topwrap’s capabilities to bring more clarity and convenience to the process of building SoCs and other digital designs. As showcased by the optimized structure of Topwrap’s YAML description files, modules and their parameters are now better structured and logically connected, the introduced clock and reset functionality along with the ability to assign default values allows more automation and sane defaults for typical use cases.

If you’re looking for a starting point that would help you design your next SoC faster and with more convenience, you can also explore Antmicro’s extensible reference Guineveer SoC design, based on CHIPS Alliance’s VeeR EL2 RISC-V core - and built entirely in Topwrap.

Building on our experience in design and verification of SoCs and IP blocks for our customers, we are constantly expanding our suite of developer productivity tools, which help speed up our customers’ development workflows. To find out more about how Antmicro can help you adopt Topwrap and tailor it specifically to your requirements, reach out to us at contact@antmicro.com.