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 designing SoCs first introduced in 2024, has continuously been receiving updates and improvements to provide a standardized approach for organizing digital design blocks for ASIC and FPGAs into various configurations, making top-level designs easier to parse and process automatically.

In our previous blog, we covered a range of functional enhancements aimed at easing the process of digital design development such as the introduction of automatic design validation, SystemVerilog frontend, support for the AXI interface, and more. Since then, we’ve been actively working to further extend Topwrap’s capabilities in an effort to make it more convenient for use with both complex and simpler designs via CLI-level configurations and 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 all components of your SoC ecosystem into clear, structured, and user-friendly digital logic designs.

Optimized YAML structure

The optimized structure of Topwrap YAML files provides even more modularity and allows for easy and concise design description, as documented in more detail in this section. You can also see detailed step-by-step instructions on how to design SoCs in Topwrap from the ground up and leverage all introduced changes 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, it’s 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 more a 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. 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 brings more automation to SoC development. All this from the comfort of a constantly enhanced GUI.

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 SoC design Guineveer, based on the VeeR EL2 RISC-V core - and built entirely in Topwrap.

In addition to designing SoCs for our customers, we also offer a suite of developer productivity tools, which help improve our customers’ tooling and speed up their development workflows. To find out more about how Antmicro can help you adopt Topwrap to design a custom SoC and tailor it specifically to your requirements with our design aggregation tooling, reach out to us at contact@antmicro.com.