Thursday, January 14, 2016

FuseSoC and IP-Xact

When I started the work on what would become FuseSoC, I had the ambition to somehow take advantage of the IP-Xact standard. Unfortunately my time to work on FuseSoC is limited, and there has been many other features that got higher priority. In the end, it might actually have been a good thing that it wasn't added until now, since it gave me plenty of time to get a feel for IP-Xact and figure out just how to best integrate it with FuseSoC.

Let's begin with a small introduction to IP-Xact.

According to Accellera, who oversees the standard, IP-Xact is "a well-defined XML Schema for meta-data that documents the characteristics of Intellectual Property (IP) required for the automation of the configuration and integration of IP blocks; and to define an Application Programming Interface (API) to make this meta-data directly accessible to automation tools"

So IP-Xact is one or several XML files that you can add to your IP core to describe certain properties of the core. There are tons of features in IP-Xact to handle different aspects of the design. These include things like register maps, external ports, source files, parameters, build commands and much more. IP-Xact files are becoming quite common as a method of encapsulating IP so that they can be integrated more easily in different EDA flows. Many of the EDA vendors are using it, even though they sometimes tend to use so many vendor-specific extensions that the IP in practice are of limited use outside of their own tools.

The observant reader will notice that some of IP-Xact's features are directly overlapping with the FuseSoC .core files. With the premise that double documentation is a bad thing, let's take a look at different options for only having one source for metadata.

  1. Just use FuseSoC .core files. This is what we have today, but the whole idea of the IP-Xact integration  is to expand the FuseSoC universe, take advantage of an existing standard and trying to not reinvent things. Also, this article would have been terribly short if I had decided on this option
  2. Just use IP-Xact files. This is a solid proposition, but my opinion on IP-Xact is that it is a flawed standard.  It's currently the best (only?) chance of a vendor-neutral standard at all though, so I can forgive some of its drawbacks, but not all of them. Some of the more annyoing problems are the file_type parameter that can be attached to each file. The latest IP-Xact standard currently defines 38 language types. Verilog is represented by verilogSource, verilogSource-95 and verilogSource-2001. VHDL has three similar options. C only has cSource and there are a few more generic such as swObject, SDC, unknown and user. The problem here is that this list doesn't stand a chance of keeping up with all the new and existing file types that people wants to use for digital design. It leaves out both VHDL 2008 and Verilog 2005, which makes it harder to decide on which compile flags to use for the EDA tools. It's also not aware of the new school of HDL like Chisel, MyHDL, Migen or Cx to just mention a few (a better solution was suggested here).

    I'm also not completely convinced by the attempt of becoming a build manager à la CMake or Apache ANT. The build management part of IP-Xact already have quite a lot of options, but not nearly enough to be flexible enough to support complex builds. I would rather see that they left this part out to avoid that the standard becomes to unwieldy.

    There are also plenty of options in the .core files that are not in IP-Xact. "A-ha!", says the experienced IP-Xact user here. "But IP-Xact has a built-in mechanism for specifying vendor-specific extension. All FuseSoC nonsense could just be marked as extensions". True, but first of all, that clashes a bit with the idea that FuseSoC shouldn't make unnecessary demands on the IP cores. One thing in particular that would be a bit complicated is how to specify where to find dependencies for a core. All this might be solvable, but I also find IP-Xact a bit too heavy and at the same time not specific enough compared to the existing .core files for some parts.

  3. My preferred option is instead to keep the .core files, but allow specifying an accompanying IP-Xact file from where FuseSoC can get additional metadata. This allows us to work with cores both with and without IP-Xact files and we don't have to make any changes to the upstream cores. We can avoid double documentation and add things to the .core files that are hard to do with IP-Xact. Win, win, win, win!

    To further motivate this decision, I'm drawing on the experience of software package managers here. To make a comparasion with the software world, IP-Xact is our AppStream file, that contains metadata for applications, that can be used in different package managers. The program itself is still put in a .deb or a .rpm file or specified by a .ebuild or pkgbuild file (the .core file). These are different layers that have some overlapping information.

For FuseSoC I'm currently using the file sets and core description, since these are options that are already available in FuseSoC and can be easily fetched from the IP-Xact file instead. There are other things in IP-Xact that could be used in the future as well, but we all know that the future is scary, so let's not talk about that.

To make FuseSoC aware of a core's IP-Xact component file, this file has to be added to the main section with the new option 'component=<file.xml>'. When the core is loaded, the file sets in the IP-Xact file are parsed and added to the list of filesets found in the .core file. There are some extra features on the roadmap here to make it possible to merge or replace filesets with similar names in both the .core and the IP-Xact file. Merging filesets can be useful as some file types (such as verilogSource-2005 and vhdlSource-2008) and other options are only available when the filesets are specified in the .core file. The group tag from the IP-Xact should probably be merged with the usage tag in the .core file as well at some point.

Note also that the  component option doesn't have to be a single file, but can also be a space-separated list of files. In this case, file sets are appended, but the description is taken from the first file that sets it.


The first IP-Xact features will be available in FuseSoC 1.4, but they are already available in git, and as a bonus, I have also put together a Proof of Concept system (a PoC SoC :)) , together with some instructions here, that uses the new features. It's a stripped down version of the de0 nano system that is available in orpsoc-cores and can be both simulated and built to an FPGA bitstream.


For those of you who haven't used FuseSoC before, you can find installation instructions in the FuseSoC repo

After installation, add the path to de0_nano_ipxact to your core library path and run
fusesoc build de0_nano_ipxact to build an FPGA bitstream or fusesoc sim de0_nano_ipxact to run a simulation in Icarus Verilog

Have fun and let me know what's good and what can be improved