IP-XACT: The good, the bad and the outright madness

I've found myself in a strange position recently defending IP-XACT on a number of occasions. Most recently there were some heated discussions with lots of hand gestures at orconf. The heat and hand gestures however might have been due to the fact that we were in Italy. Still, there were discussions.

So let me get this straight once and for all by quoting one of the great thinkers of the 21st century.

IP-XACT is in most parts horrible, but it's the best chance we have for a vendor-neutral standard.

O. Kindgren, 2016

So what is this mostly horrible but still kind of useful standard? It's an IEEE standard developed by Accellera aimed to create an interchange format for IP cores. You can find the standard here, but the Wikipedia article does a better job at capturing the purpose and extents of the standard in a few sentences.

IP-XACT is an XML format that defines and describes electronic components and their designs. IP-XACT was created by the SPIRIT Consortium as a standard to enable automated configuration and integration through tools.

The goals of the standard are

• to ensure delivery of compatible component descriptions from multiple component vendors,

• to enable exchanging complex component libraries between electronic design automation (EDA) tools for SoC design (design environments),

• to describe configurable components using metadata, and

• to enable the provision of EDA vendor-neutral scripts for component creation and configuration (generators, configurators).

These are all noble goals, so why the criticism? First of all, it's an XML-based standard. This alone will turn away many people, but frankly, don't tell me that json is any better. For some reason though, json has managed to attract a lot less negativity while still being affected by some severe shortcomings and compatibility problems. My personal pet peeve is that there isn't any way to add comments to a JSON file, which is very annoying when you want to temporarily remove a part of the file, or explain something. For those of you who don't know json that well, it looks a bit like LISP code with wrinkles.

With that out of the way, another problem is tool compatibility. As with most standards in the FPGA world, the two giants, Xilinx and Intel (still haven't gotten used to saying Intel instead of Altera) does a superb job of never backing the same standard, to ensure an absolute minimum of interoperability. Prior examples being Xilinx endorsing the FMC standard for daughter boards with Altera going for HSMC. Xilinx used to have their UCF constraint format which didn't look like any other constraint format, but have now moved to XDC, which is almost but not quite compatible with the more common SDC format. In the case of IP-XACT, Xilinx supports it, but not Altera

Actually, supports is a bit too strong a word in this case, as Vivado only works with up to the 2009 standard, not IP-XACT 2014. ISE of course doesn't handle IP-XACT at all, but I guess that's ok since it has been obsoleted since some years. Actually, when I say that Vivado supports up to the 2009 standard I'm still being a bit too kind, and this brings me to the first issue with IP-XACT

Vendor extension

Vendor extensions means that tools are free to define their own non-standard XML tags in the IP-XACT files. This allows them to implement additions where they feel the standard is lacking. This can be a good thing, but the drawback is that it opens up for a lot of non-standard additions, where every vendor implements the same functionality in different ways. I've seen examples where most of the file is just encapsulated in vendorExtensions. Incidentally, this is a bit similar to what happened to the other vendor-neutral EDA standard, EDIF, where no two files from different vendors were really compatible with each other. Wikipedia has a fascinating article about EDIF, which should serve as a cautious reminder to the future of IP-XACT

Tool support

What about IP-XACT support in other tools then? Unfortunately most commercial IP-XACT tools are out of reach for someone not deeply entrenched in ASIC development, so my other examples will be open source tools. The likely most used open source tool for working with IP-XACT is Kactus2. Kactus2 is a graphical application where you can fill in the various fields of an IP-XACT component file in a more or less user-friendly manner. It can parse Verilog/VHDL code to help you import existing HDL code into an IP-XACT model. Once you have built up a library of files, you can hook them up together in a block diagram view and export the top-levels as verilog or VHDL together with documentation, C header files for registers and a few other things. Kactus2 up to version 2.8 only handled the older IP-XACT 1.5 version, while Kactus2 3.0 (yes, it's Kactus2 3.0, not Kactus3. I asked the developers) and onwards only handle IP-XACT 2014. The attentive reader will notice that this means that Kactus2 and Vivado are no longer able to work with the same files.

For my own humble uses of IP-XACT, I decided to write a small python library called ipyxact to easier interface the parts of IP-XACT that I care about. This means it only support a limited subset of the standard. On the upside, it reads and writes 1.5, 1.6, 2009 and 2014 files, and there are some ideas how to make it cover the full standard. So, as you can see, there are still tools to be written for IP-XACT. For the IP-XACT files themselves Accellera provides XSL scripts which can be used to automatically upgrade files to a newer version. (Hey JSON, you got something like XSLT? No? Didn't think so either)

What about the good parts then? There must be something good to say about IP-XACT too. Fortunately, there are some good parts, and these are enough for me to endorse it, even with its numerous other faults.

VLNV tags

Each named object, such as a component or bus in IP-XACT have an identifier called VLNV. VLNV stands for Vendor, Library, Name, Version and is used to uniquely describe an object. These are often written as a colon-separated string, such as librecores.org:peripherals:uart16550:1.5 Even though it sometimes can be a bit awkward to come up with a good naming scheme for Vendor and Library, it will work out fine for most use cases, and the four fields are enough to avoid any namespace conflicts. Well done IP-XACT!

Block diagrams

One part of the IP-XACT standard allows you to define the interfaces of your IP cores. This can be single wires, but more common is to group these together into a bus, such as Wishbone or SPI, which can be connected between components. There are several graphical editors to help with this too. Kactus2 is the main example, and is also Open Source. Vivado comes with a built-in block diagram tool which is based on IP-XACT too. I love this part of the standard. I always draw my designs on paper before getting to work, so why not be able to use this for both documentation and implementation? I know that many of the new HDL such as Chisel and Migen was born partly out of frustration of connecting components in Verilog and VHDL. These languages makes it a bit easier, but it's still programming code, and in my opinion this is a graphical problem best solved with a graphical tool. Do your business logic in your language of choice, but leave the interconnections to a drag-and-drop application. Kactus2 still has some ways to go to make this really comfortable, but it works fine for many cases and I have done a few Proof of Concept designs to get better acquainted with the process. The drawback here is that it's not that flexible. Even though interfaces can be parametized with regards to widths and types, I haven't found a way to create components with a variable number of buses, which is handy for things like bus interconnects where you want to quickly hook up or remove master and slaves. My solution for that is to use my trusty ipyxact library to generate application-specific wrappers for these components. It works, but requires an extra step. There is unfortunately another problem with the way bus interfaces work in IP-XACT. Each bus type is identified by a VLNV tag. This means that a one_vendor:buslibrary:busname:version is not compatible to other_vendor:buslibrary:busname:version. And you know what? IP vendors are happy to put their own names on things, but not their competitors, so this will happen a lot.

In all fairness, this problem comes down to management of the shared resources and Accellera are providing bus definitions for a few common buses, like SPI and the various MII variants to connect ethernet Phys and MACs, but it would be great if other owners of buses would do the same as well. For LibreCores we are planning to host open standards such as Wishbone and we're happy to help if other want to host their standard bus defintions here as well

 File sets

File sets lists the files of an IP. Each file contain information such as file type, if it's an include file, which library it belongs to and other metadata. The filesets themselves have additional properties such as describing its purpose. This can for example be used to expose different filesets for simulation or synthesis. The filesets are actually the only part of IP-XACT that is currently supported in FuseSoC. Instead of listing the files directly in the FuseSoC .core files, a .core file can point to an IP-XACT component file and FuseSoC will automatically pick up the files from there. And even if you prefer to use only .core files, the fileset sections in the .core files are modeled after the structure in IP-XACT. Sounds good? Mostly, yes, but there are some drawbacks. First of all, the files can contain a lot more metadata than what is listed above, but I will return to that later. Instead, I will focus on the file types. The IP-XACT standard decided to enumerate all valid file types in the standard. Here's the complete list for the latest (2014) revision.

unknown, cSource, cppSource, asmSource, vhdlSource, vhdlSource-87, vhdlSource-93, verilogSource, verilogSource-95, verilogSource-2001, swObject, swObjectLibrary, vhdlBinaryLibrary, verilogBinaryLibrary, unelaboratedHdl, executableHdl, systemVerilogSource, systemVerilogSource-3.0, systemVerilogSource-3.1, systemCSource, systemCSource-2.0, systemCSource-2.0.1, systemCSource-2.1, systemCSource-2.2, veraSource, eSource, perlSource, tclSource, OVASource, SVASource, pslSource, systemVerilogSource-3.1a, SDC, vhdlAmsSource, verilogAmsSource, systemCAmsSource, libertySource, user

Quite some list, right? Both SystemVerilog 3.0 and SystemVerilog 3.1 is there. There are also something called executableHdl which I have no idea what that is. Looks like everyting is covered. Well, what about verilog 2005? Not a major language revision, but they added $clog2 in that version which is quite handy. Or VHDL 2008? That one is really big. Turns out that they forgot about those. There are also a gazillion new HDL languages such as Chisel, MyHDL, parC as well as all the vendor-specific IP formats, which have no entries in this list. For FuseSoC, I have added a few new file types (currently QIP, verilogSource-2005, vhdlSource-2008, xci and xdc) which have been required, which already makes it a superset of IP-XACT. Enumerating types like this is just a bad idea, and we will see even better examples of this later on in this article

 Register maps

Register maps is one of those areas where you want to make sure that the documentation matches the implementation. For this reason it makes sense to have a single source format from which you can create nice looking tables, C header files, slave interfaces for various CPU buses and perhaps test vectors. Most projects I have been working on have had different strategies for this. Many just do an implementation for a single bus interface and use a separate document where the designer has to do the tedious and error-prone work of writing down the same information and remember to tell the software developers when and how to update their C header files. This is of course very often not kept in sync. One magnificent example is a company, which shall be left unnamed, which stored all their registers in a spreadsheet file which was put under version control as a binary file and parsed this file with some magic scripts to extract the information. Nothing has ever gone wrong when parsing spreadsheets, right? And comparing two versions of a spreadsheet is always a joy.

IP-XACT, while being a XML-based format which some smarty-pants will always claim is actually a binary format, makes it a lot easier to keep the different target formats in sync. The register maps in IP-XACT capture enough information to describe most common access types, such as read-only, clear-on-write, single-shot and different bits slices of a register can be fully independent from each other. As usual with IP-XACT it's also possible to set some less common properties, such as marking a register as readWriteOnce. Might be useful if you're implementing a CD-ROM perhaps, I don't know.

Let's discuss the drawbacks then. Well, it turns out that the IP-XACT standard committee themselves didn't think register maps were good enough, so they came up with yet another format called SystemRDL, which they recommend using to *drum roll* generate IP-XACT register maps! So despite having added all these really complex features to express all details about registers they recommend moving to another, even more expressive format, to create the register maps. Maybe they should consider, perhaps, dropping register maps all together from the standard if that wasn't good enough? It's not like IP-XACT would be too small without the register parts. Instead, it seems like they are adding more features to registers for every standard revision. And this thing about adding features to the standard brings me to the really scary parts. Let me present:

IP-XACT as a build system

Every file listed in a fileset has some metadata, as I mentioned above. One of these metadatums (not at all sure that's the correct word for a single piece of metadata) is the buildCommand. It is a whole XML tree structure used to describe how to build said file. It comes with a ton of complex options used to describe which flags to use for building and then linking the file. Flags can be taken from a default build command, overridden by the build command specified for the file or taken from its sibling files, all according to some vaguely defined rules. Having a single buildcommand is of course impossible to combine with tool-independence since there is no standard command to deal with HDL files. Each tool has its own syntax and structures. Embedding this in the IP-XACT files is just wrong! Ok, let's assume that this isn't for HDL files then. Since building and linking is explictly mentioned in the tag names, we can guess that this is aimed at C code. Problem is, this can work totally different for other languages. Even for C files, this is a problem, since it's not really possible to switch between gcc, llvm or other compilers. There are also no way to do conditional compilations based on which flags are being set at a higher level. Please, please, please IP-XACT. Leave this task to experienced software developers. There is already an endless list of build systems for software (autotools, cmake, meson, scons, waf...) with decades of work to get them to the state where they are. Many of them still have some really bad limitations and the last thing the world needs is another half-assed build system designed by RTL designers who's only exposure to software structure was taking a class in Java back when Spice Girls topped the charts. This is unfortunately all too symptomatic of the EDA standards, and no amount of craziness in the IP-XACT standard manages to come close to the proposal to add inline Perl in SystemVerilog. Sometimes I think we're just doomed.

Speaking of software, this leads me to another favorite part of IP-XACT

IP-XACT to describe software API

Digging deep into the dark corners of IP-XACT, you will find that each fileset can be matched to a "function". The documentation of this particular tag says "Generator information if this file set describes a function. For example, this file set may describe diagnostics for which the DE can generate a diagnostics driver". Ok, not all that clear what this means, but let's move on and see what's beneath this function tag. There is a tag called entryPoint, which apparently is the Optional name for the function. There's also a fileRef, which is used to describe A reference to the file that contains the entry point function. Likely, those two are related somehow. There are a couple other tags as well, but the real gem is returnType, with the helpful documentation saying Function return type. Possible values are void and int. Yes, as we all know, int and void are the only two types a function will ever return. Let me illustrate this by a short conversation

- Hi Mr ipxact_square_root_function!
- Hi!
- Do you think you could give me the square root of three
- Certainly! It's my pleasure. The answer is.... let me think... one!
- One?
- Yes, one.
- Are you.. I mean, shouldn't that be more like... is that really...?
- Look, you should be happy that I gave you something. Or would you prefer I give you void instead?
- No no no! One is fine, one is fine. My bad
- I thought so
- (grumble grumble, I'm not asking that one again)
- What did you say?
- Oh! No, nothing. One is fine. Moving along

So my point here is that large parts of this standard manages to be extremely complex, while at the same time having strange limitations that makes them mostly useless. Couldn't we just fix these parts of the standard then? Well, this leads me to

IP-XACT, the free standard

To take part of the decision making progress, all we need to do is becoming members of Accellera, which can be done by registering on their home page. Oh, and you need to pay $25000 too. As much as I'd love to take part in steering this standard away from it's very uncertain path, I have a hard time imagining myself going to my boss and say "Hey, I need $25000! Why? Someone is WRONG on the internet. I need to fix this". Instead we have participants from the usual suspects in the EDA industry, and ideas from academia and the general software industry are nowhere to be found

The verdict

Having worked as a contractor on FPGA/ASIC designs for many years as well as digging into dozens of different Open Source Silicon projects, often with the purpose of packaging them for FuseSoC, I have come across many many, ways to do the exactly same thing. I'm dead tired of having to learn yet another register map generator or IP core description format only to find that I need to write another set of tools to automate the process. It's incredibly time-consuming, and this is why I cheer for IP-XACT, despite its numerous faults. It's a standard way of dsecribing IP cores. Given some time and effort, I think that there will grow a healthy ecosystem around the standard, and I think in fact that it's absolutely required to have everything from full-blown environments to small utilities for dealing with IP-XACT. Otherwise, no one will see the point of supporting this multiheaded beast of XML.

I also hope that the EDA industry will come to its senses and see that much innovation and knowledge never reaches the standards as long as the organizations charge these sums of money to participate. Also, if the standard continues to branch out with more of these half-baked ideas, it will die under its own weight. If that happens I hope the good ideas will be forked off to a new standard, hopefully driven by a more inclusive organization. But I hope that won't happen at all, because it would likely result in ten similar standards fighting for attention, and as I mentioned in the outset, this is the best chance we have for a vendor-neutral standard. Let's go with the flow and see where it takes us. We can always jump ship later.