Topwrap is Antmicro’s tool for designing System-on-Chips, both for ASIC and FPGA targets, supporting HDL design files parsing with automatic inference of interfaces, YAML-based description for command-line use, and a user-friendly GUI based on the Kenning Pipeline Manager, all of which we described in detail in our introductory blog post on Topwrap. Topwrap excels at modularity, with reusable design blocks, and enables automation for the design process. We also described how we used Topwrap to generate Guineveer, our reference SoC design based on the RISC-V VeeR EL2 core, so you can easily base off of it and quickly create your custom SoC.

Expanding on Topwrap’s capabilities, we added new features to further improve and ease the process of SoC design, such as better SystemVerilog handling of complex designs, and support for the AXI interface, auto-generation of component interconnects, and automatic validation of the design. In this blog post, we’ll take a closer look at what these new features offer and how you can use them in practice.

Complex designs in Topwrap with auto-validation and better interconnects

SystemVerilog handling of complex structures

Topwrap was able to parse resource files before, which was, however, limited to Verilog files only. With the new SystemVerilog support, we opened up an array of new options.

We added a SystemVerilog frontend based on pyslang, extending Topwrap’s capabilities of understanding interfaces and complex structures in the input data. There is also a backend that relies on processing templates, producing human-readable code in SystemVerilog that describes those interfaces.

For comparison, here is the (trimmed!) Verilog output from the older Topwrap:

(* top =  1  *)
(* generator = "Amaranth" *)
module project_top(PORT_CLK, PORT_RST, PORT_IN, PORT_OUT_0, PORT_OUT_1, PORT_OUT_2, z);
  (* src = "<...>/amaranth_helpers.py:64" *)
  input PORT_CLK;
  wire PORT_CLK;
  // <other port direction definitions...>
// [!code lines=26]
  (* src = "<...>/amaranth_helpers.py:64" *)
  wire ip_ibuf_clk;
  // <other internal wire declarations...>
// [!code lines=55]
  project_top.ip_ibuf  ip_ibuf (
    .a(ip_ibuf_a),
    .clk(ip_ibuf_clk),
    .rst(ip_ibuf_rst),
    .z(ip_ibuf_z)
  );
  project_top.ip_iobuf  ip_iobuf (
    .a(ip_iobuf_a),
    // <other ports...>
// [!code lines=68]
  );
  project_top.ip_obuf  ip_obuf (
    .a(ip_obuf_a),
    // <other ports...>
// [!code lines=75]
  );
  assign PORT_OUT_2 = ip_ibuf_z;
  // <other assignments...>
// [!code lines=89]
  assign ip_obuf_clk = PORT_CLK;
endmodule
(* generator = "Amaranth" *)
module project_top.ip_ibuf (rst, a, z, clk);
  (* src = "<...>/amaranth_helpers.py:64" *)
  input a;
  wire a;
  // <other port/internal wire declarations...>
// [!code lines=106]
  ibuf ip_ibuf (
    .a(a),
    <...>
// [!code lines=111]
  );
endmodule

module project_top.ip_iobuf (rst, oe, a, y, z, clk);
// <wrappers for remaining modules...>

And here is the full new SystemVerilog output from Topwrap:

module project_top (
    input logic PORT_CLK,
    input logic PORT_RST,
    input logic PORT_IN,
    output logic PORT_OUT_0,
    output logic PORT_OUT_1,
    output logic PORT_OUT_2,
    inout logic z
);

  ibuf ip_ibuf (
    .clk(PORT_CLK),
    .rst(PORT_RST),
    .a(PORT_IN),
    .z(PORT_OUT_2)
  );

  obuf ip_obuf (
    .clk(PORT_CLK),
    .rst(PORT_RST),
    .oe(PORT_CLK),
    .a(PORT_IN),
    .z(PORT_OUT_0)
  );

  iobuf ip_iobuf (
    .clk(PORT_CLK),
    .rst(PORT_RST),
    .oe(PORT_CLK),
    .a(PORT_IN),
    .y(PORT_OUT_1),
    .z(z)
  );

endmodule

This enables users to efficiently analyze the code output of their design, check for errors, identify opportunities for optimization, as well as help with conformance with defined formatting and linting rules.

Support for structs as ports in SystemVerilog frontend

SystemVerilog structures are one of the ways to reduce code duplication, by grouping related signals together and enabling reusing the definitions. Interface deduction in Topwrap works the same way with modules using structures as with modules with regular ports.

One example of where this is applicable is Antmicro’s Guineveer sample SoC design. The SRAM module, with its own native ports, now has a customizable interface (signal group) in SystemVerilog. Instead of the flat wrapper that exposes flat ports, Guineveer can make direct use of SystemVerilog modules that have structure ports.

Previously, for the SRAM module, a wrapper module with flat ports was needed:

module sram_wrapper (
    input logic        clk_i,
    input logic        rst_ni,

    // AW channel
    input logic        awvalid,
    output logic       awready,
    input logic [31:0] awaddr,
    // ...
    // B channel
    output logic       bvalid,
    input logic        bready,
    output logic [1:0] bresp,
    // ...
);
    // ...
endmodule

In the newest Topwrap, you can use the structure ports directly:

typedef struct packed {
    aw_chan_t aw;
    // ...
    logic b_ready;
    // ...
} axi_req_t;

typedef struct packed {
    logic aw_ready;
    // ...
    b_chan_t b;
    // ...
} axi_resp_t;

module guineveer_sram (
    input  logic clk_i,
    input  logic rst_ni,
    input  axi_req_t axi_req_i,
    output axi_resp_t axi_resp_o
);
    // ...
endmodule

Note that the definitions for axi_req_t and axi_resp_t can be reused multiple times.

Support for the AXI interface

While Wishbone support was already implemented, we added support for AXI interconnects, based on open source implementations such as PULP. This necessitated extending both the YAML and IR formats in Topwrap to store the information about the interconnects. With the integration of Kenning Pipeline Manager, you can easily create blocks with configurable numbers of ports for manager and subordinate components.

In another step, we extended the mechanism for deducing different types of buses, including AXI4 Stream, AXI4 Lite, AXI4, and Wishbone, added hints about signal grouping, and enabled storing custom definitions of buses, for inference of user-specified interfaces. For example, we created a custom interface definition for AHB within the Guineveer project in order to connect OpenTitan’s UART peripheral.

Adding new interface definitions is simple, as the YAML description file just needs to be placed in the correct directory in a repository, and Topwrap will pick it up automatically. Adding the definition allows the user to take advantage of it without any additional changes in Topwrap. The design process now adheres to a standardized on-chip bus interface (e.g., AXI4, Wishbone) to ensure seamless integration and swapping. You can freely modify the number of managers and subordinates and the address map that you need to use with your interconnect. Topwrap automatically updates the connections between the components, as specified by the user (in the YAML file or in Topwrap’s GUI).

Feel free to test the interconnect handling in Topwrap by yourself:

Interconnects in Topwrap GUI: sandbox (static) Visit the desktop site to make use of this interactive sandbox.

Auto-validation of designs

In digital design, systematic validation checks are essential to ensure correctness, maintain consistency, and catch issues early before they propagate to later stages of the flow.

Topwrap incorporates internal checks and constraints to prevent illegal or conflicting configurations and to detect a wide range of errors.

For example, as you can observe in the recording below, Topwrap will:

  • prevent you from creating mismatching/invalid connections.
  • detect any missing connections.
  • warn you of any duplicates in block names.
  • invalidate block parameters or notify you about any missing ones.

In the recording below, you can see how Topwrap prevents you from creating invalid connections, by highlighting them in red when you attempt to connect them to invalid ports (shown in gray):

In turn, the recording below showcases how you can validate your design to check it for any errors, such as missing connections:

This takes away the large effort of having to identify and resolve such issues manually.

Repository management, with custom interface mappings and definitions

For convenient management of your projects in Topwrap, we added the topwrap repo command that enables you to manage your repository and add new items to it.

Your repository can contain your (custom) IP cores, as well as interface mappings and definitions. It enables convenient sharing of building blocks for Topwrap between teams and people.

As your repository is structured using a text-based format, this enables quick and easy integration of a version control system such as git. Our team uses this functionality to manage different versions of the Guineveer sample SoC design.

To create new repo, use: topwrap repo init your_repo_name your_folder_where_repo_is_stored

Then you add a file to it by using: topwrap repo parse my_repo_name ipcore.sv

When topwrap repo parse is used, it adds an IP core to your repository; use the --inference flag to add interface mappings and enable deducing interfaces based on port names.

Future improvements

Based on the recent improvements to Topwrap, which we continuously work on, we were able to determine what future enhancements would best complement those we already introduce. The planned future improvements to Antmicro’s Topwrap include:

  • Support for more system bus protocols/interconnects (such as APB),
  • Automatic conversion between bus protocols,
  • Library of reusable components (IP blocks),
  • Plugin-based extension mechanism for extending Topwrap’s functionality,
  • Enhanced GUI-based design configurability through configuration windows,
  • Better SoC frontend, aligned with the REPL (Renode Platform File) format.

Additionally, the connected component library will include a diverse set of essential peripherals that you will be able to browse (e.g., DMA, Ethernet MAC, various timers, GPIOs, and security elements) to enable designs for different application domains (embedded, IoT, accelerator), including support for multi-purpose designs. The library will have a hierarchical structure (with the IP blocks instantiated within wrappers), in order to isolate and protect the generator logic from changes to individual IP blocks.

Antmicro’s open source design ecosystem, at your disposal

Topwrap enables you to quickly and conveniently connect IP blocks to create an entire SoC design. You can rely on automation for generating and validating connections on a bus level, load and store IP cores in a custom library, and use a convenient GUI to oversee and manually modify the designs, for a smooth and convenient design process.

You can commit Antmicro’s expertise in Topwrap and SoC design to developing a new open source I/O core with our design aggregation tooling, and we can also help you expand your developer toolset and optimize your in-house design process. Feel free to message us at contact@antmicro.com to discuss your needs.