Happy 100k!

Sure, it's not a million, but then again I'm not Arianna Huffington. Given how extremely niche these topics are and that blogging has been declared dead for about a decade now (about as long as I have been blogging, come to think of it), I think that a hundred thousand visitors is actually really really good. It's sure is a lot more than I would ever had imagined when I started doing this ten years ago.

The proof! Also notice the massive amount of followers this blog has gathered over the years

 

I don't remember anymore why I started blogging but I guess I felt that the world deserved to hear my opinions on random things. Also, there wasn't really anyone else writing about the things we were doing with OpenRISC and open source silicon in general at that time. Nowadays, any industry conference and news outlet worth mentioning will have FOSSi content but back then, most people in the industry just didn't get it. (To be fair, most industry people still don't get it given the number of "open source" panels I have seen at conferences consisting of people with zero insights who just sit there making up stuff because their companies have paid to have them there. Thank god for events like ORConf and Latch-Up!).

Enough about why. I thought it could be fun to look at how instead. There are a number of events that have lead to the magic six figure number. So, let's go back to the beginning. What was supposed to be the first article actually became the second article because when I wrote it I went off on a tangent and ended up with a whole article on scope creep instead. And I think that pretty much sums up my writing and how I (fail to) get things done in general by starting something and then ending up getting stuck in some detail and end up doing something completely different instead. Not that it really mattered though. The readership consisted mostly of friends who I forced to read the blog and questioned them afterwards to make sure they had read the whole thing. But I kept writing every now and then about different things around the OpenRISC archicecture. And then one day the people in my regular IRC chat channel notified me that my latest blog post was on the frontpage of Slashdot! For all you youngsters out there, Slashdot used to be the place where all nerds got their news and if you were featured on the Slashdot frontpage during its heydays you'd better have a server that could handle a massive influx of traffic. There were stories about servers burning up after being "slashdotted" because they were humble machines that never thought they would see so many visitors in their life. Luckily, 2014 was a bit after the heydays of Slashdot and Google hosted the blog so I don't think anyone got particularly worried about overloaded servers. But it did make some difference in numbers for the statistics for this humble blog.

The Slashdot effect in action

 

A couple of hours later, the Slashdot crowd moved their attention elsewhere and never came back, as is painfully clear from the statistics. I kept writing now and then however, mostly about FuseSoC, FuseSoC and FuseSoC which apparently didn't lead to any new front page news. A couple of years later though, I wrote about my complicated love-hate relationship with IP-XACT and that seemed to have struck a chord with some people. This one was more of a sleeper hit that didn't cause any immediate sensations but eventually became my most read, and definitely most cited, article I had written.

IP-Xact - an evergreen of confusing and questionable EDA standards

Getting noticed in premier geek media and cited in academic circles have both been happy surprises. There's no getting around that does feel a little more fun writing when you get these kind of validations. So I kept writing to a tiny uptick in readership after the IP-XACT article, again mostly about FuseSoC, FuseSoC and FuseSoC, but after starting way too many FOSSi projects over the years, like SERV, SweRVolf and Edalize, I also started doing yearly round-ups partly to remind myself what I did over the past year. And then one evening, after spending a day in a workshop with a clueless EDA vendor trying to shove their awful tooling down our throats, I wrote about one of the FOSSi projects that I believe will have a large impact the coming years, namely cocotb and how it will save us from SystemVerilog for verification. And that, my friends, turned out to be of more interest than anything I had previously written about.

Cocotb and Python coming to steal the show, as always

Suddenly, the hordes of geeks coming via Slashdot was just a blip on the radar compared to the angry, happy, confused and relieved verification engineers who showed up en masse to state their opinions, tell their stories, show their support or ask what this was all about.

Not everyone agreed, but it was clear that it was a hot topic. And that's the third thing I'm really happy about, to have ignited discussions around the status quo of chip design and get people to bring their ideas and opinions to the table.

I really hope to continue writing about stuff when I'm in the mood and can find the time. And hopefully some people find it interesting, at least occasionally. Given the sporadic output of the past, we will never know the next time that happens, so I'll just say until then!

FOSSi Fantasies 2022

 

2022 is behind us and as usual I'm wrapping up my open source silicon efforts of the past year in a blog post.

Hang on...a 2022 retrospective...? In... the end of April??

Yes, I am fully aware that a third of 2023 has already passed, thank you very much, and that it's way too late to write a new year's retrospective. I have just been extremely busy, but I still wanted to get it out of the system. It's only been a month since the Persian new year, so in the light of that I'm not that late. Anyway...

This year, the list is shorter than usual simply because I haven't done as much FOSSi work as previous years. The upside is that I managed to complete this article close to new year, rather than much later as in previous years.

But why have I done less work? The main reason is that I have been terribly busy with my day job which is mostly of proprietary nature. While I do a lot of interesting stuff in this capacity, it's unfortunately not much I can talk about publicly. This is another reason why I greatly prefer open source work, so that I can show, share ideas and collaborate with other people.

There is one thing however from my day job that I can and want to talk about. This summer we launched a fully remote office that we call Qamcom Anywhere. Having worked remote myself for the past four years I have been pushing to make it possible for more people in the company to do the same, and this year we got it going for real. Qamcom Anywhere has been a massive success and we have found amazing new colleagues in various parts of Sweden where we previously haven't been looking before. Given my previous experience with working remote as well as working on open source projects, which by nature tend to be highly distributed, I was tasked to run this new office. As part of the campaign we also recorded a commercial, so I can now also add movie star to my CV ;)

As for now, we have launched Qamcom Anywhere in Sweden, but hope to spread to more countries in the future. Stay tuned if you want to be colleagues!

But even outside of this I have found some time to work on my long list of open source silicon projects.

Let's start by looking at what has happened to FuseSoC over the past year. Most of the effort has been spent on getting FuseSoC in shape for a long overdue 2.0 release. A couple of major features and changes were identified as being important to complete before this release. Most notably is the support for the new flow API in Edalize, but a number of critical bug fixes and backwards-incompatible changes were put in place. Unfortunately, we never manages to get the 2.0 release out of the door, but we got close and at least released a first release candidate in late December, while the final release saw the light in the beginning of this year.

Most of my other FOSSi projects made good progress. There were a few new Edalize releases, SweRVolf got some new board support, a maintenance release to an old i2c component that I maintain (hey! it's important to put some effort into cleaning up old code, not just rewrite new code all the time) and even good old ipyxact saw a new release, which now contains ipxact2v, a very handy tool to automatically convert IP-XACT designs to Verilog top-levels. It's not fully complete, but the functionality that exists is already coming to good use in various projects.

The project that probably saw the most interesting news in 2022 was SERV. SERV itself gained support for compressed instructions, thanks to Abdul Wadood who I had the great pleasure of mentor through Linux Foundation's LFX Mentorship Program. And aside from improvements to the core itself, in 2022, fellow FOSSi superstar developer Florent Kermarrec, who might be most known for Litex, managed to run 10000 SERV cores in a Xilinx FPGA. This seems to be the current world record right now for the most RISC-V cores in a single device, but I'm very curious how the competitors will react (looking at you, Intel!).

This year was the first in three years where I didn't create any new videos (or Fully Immersive Multimedia Edutainment Experiences, as I prefer to call them). Instead I did a number of presentations using old-fashioned slides for a live audience. The first of them being the RISC-V Week in Paris in early May where I did both a presentation on FuseSoC as well as one on SERV. The SERV video was unfortunately never published, but the slides for the presentation called How much score could a CoreScore score if a CoreScore could score cores? can be found here. I did another FuseSoC talk at FPGA World in Stockholm, Sweden which was also not recorded, but the final one, from the RISC-V Summit in San Jose was. This one was title SERV: 32-bit is the new 8-bit and aims to look at how RISC-V can be competitive in the traditional 8-bit market thanks to SERV.

Both at the RISC-V week as well as the RISC-V Summit I also got the chance to meet with the people behind RVFPGA, a project I have been involved with almost since the start. For those unaware, RVFPGA is a free computer architecture course by Imagination University Programme that runs on a slightly modified version of SweRVolf that I built a couple of years ago. Right after the RISC-V Summit I also got the chance to watch a RVFPGA workshop in action, and it was super fun to see all these students working their way through the labs.

Let's see.... what else then...hmm... you know what? I'm sure other things in 2022 as well, but my memory is fading and May is just outside the door waiting to come in, so let's just cut it here before the rest of the year passes too. Here's to 2023. Happy new year!

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.

FuseSoC 1.5

Finally! FuseSoC 1.5 is now released. I was just about to release it a few weeks ago when I discovered two quite serious bugs. Then I was just about to release it when I had written a lengthy blog post describing some of the new backends. At that point I realized that it would be better to write those bits as part of the documentation. Yes, you read it right. Documentation. This release has 45% more documentation than previous releases. A massive increase from 245 lines to 368 lines. Oh well. One day it will all be properly documented...I hope. At least the new backends are documented and I will try to give the old ones the same treatment. Promise!

Now for the good stuff...

 New backends

This version adds support for one new simulator, one new FPGA flow and three EDA vendor IP package formats.

The new FPGA flow is for the awesome project IceStorm, which provides a complete open source flow for building FPGA images for Lattice iCE40 devices. The tools for this consists of yosys to handle synthesis, arachne-pnr for place & route and icepack for creating the binary file. Both yosys and arachne-pnr can handle other vendor's devices as well, and I hope to use these tools in other flows as well in the future.

There is support for an open source VHDL simulator called GHDL, which is most likely the open source EDA tool with the best VHDL support.

The new IP package formats being handled are Altera QIP files, Xilinx Coregen files (for ISE) and Xilinx xci files (for Vivado). The last two deserves a few extra words since they use the provider mechanism as a plugin system in a clever way. Providers, in the FuseSoC world, are modules that are normally responsible for downloading a core and put it into the cache. There are providers already for getting cores from git and svn repos as well as from simple URLs. The providers are each responsible for their own options but typically look something like this

[provider]
name = github
user = olofk
repo = wb_bfm
version = v1.0

One FuseSoC user and contributor however realized that the provider doesn't really have to download anything, and can instead be used to do transformations on source code instead. He implemented this to generate HDL code from vendor IP core descriptions and added the new coregen and logicore providers. They each look like this

[provider]
name = coregen
script_file = <coregen ip description>.xco
project_file = <coregen project file>.cgp

[provider]
name = logicore
script_file = <generator script>.tcl
project_file = <vivado ip description>.xci

When a core with one of these providers is requested, the Xilinx IP generation tools for ISE or Vivado are invoked to generate the HDL code, which is then placed in the cache. For the coregen-based cores, the generated HDL files are listed in the .core file as would have been done for any core.

For the Vivado-based logicore IP however there is an extra trick. As Vivado generates an IP-XACT component description for its generated IP cores, we can simply point to that one, and automatically let FuseSoC get all the HDL files for us automatically.

I have been planning for several years to do some kind of plugin mechanism to run custom preprocessing commands on source files, and using the provider mechanism for this solves the problem in most cases. Examples of future providers could be to turn MyHDL, Migen or Chisel code into verilog, or build a verilog top-level from an IP-XACT design file. As this was not originally my idea, I was naturally extremely sceptic of the whole idea. It does have some limitations, but for most cases it gets the job done and is a clever solution for the problem.

Continious integration

Another great addition brought in by a new FuseSoC user is the continious integration testing with Travis and AppVeyor. Every time something is commited to the FuseSoC repository, Travis and Appveyor are triggered to run some basic tests. As an interesting note, it took less than a week after adding the CI support until this found a bug caused by a minor difference between python 2 and python 3. That bug would probably had gone unnoticed for a long time if not for this, so it's worth its money already. Especially so, since both services are free to use.

Windows compatibility

The same user who brought in the CI testing also done some changes to the build system to increase the windows compatibility. It still doesn't run properly on Windows, but it can now at least install, list the cores properly and run a few simulations

Improved parameter handling

There had been several improvements to the handling of command-line parameters for compile-time or run-time configurations. It's now possible to specify a default value for parameters. This can be useful to override default settings in the upstream code, for example to specify a different path to a memory initizalization file than what the upstream project uses. There is also some visual improvements to the output of fusesoc {sim,build} <core> --help to make it clearer what kind of parameter is being changed. Several bugs has been fixed in this area as well, and it should now be possible to use top-level parameters with all tools.

The old [plusarg] sections that were deprecated in favor of the [parameter *] sections are no longer parsed as I have decided that users have had enough time to migrate to the parameter sections. The warning still remains to remind everyone that it's time to move on and the article about FuseSoC 1.4 has more info on what the [parameter] sections should look like.

Improved ModelSim backend

The Modelsim backend has been rewritten, both to support loading user-specified TCL files and to make it easier to rebuild a design from the exported sources. And believe it or not, there is even documentation for the modelsim backend now!

Build system changes

Finally, I also decided to remove the old autotools scripts for installation. For some time it has been possible to install FuseSoC with either python's setuptools (e.g. pip install fusesoc) or autotools (e.g. ./configure && make && make install). With the improvements in the setuptools based system, it makes little sense to keep autotools. I don't want to keep two tools updated, so from now on, FuseSoC will only use setuptools for installations. Farewell autotools. It's not you, it's me

And...

...as always, tons of bugs were killed during the making of this release. A few notable ones are that VHDL and SystemVerilog are now supported properly in ISIM, IP-XACT 2009 and 2014 files are supported, RTL library affiliation is read from IP-XACT logicalName tags and FuseSoC doesn't crash anymore if it encounters an unknown simulator in the simulators list

I'm really excited to start working on FuseSoC 1.6 now. There are already a bunch of new things ready to be commited, that I have been holding off until FuseSoC 1.5 was released. Make sure to check the git repo for daily progress if you want to get all the new things before the next version is released.

Thanks for listening!

FuseSoC 1.4

When I consider the magnitude of the subject which I am to bring before my readers-a subject, in which the interests, not of this country, nor of Europe alone, but of the whole world, and of posterity, are involved: and when I think, at the same time, on the weakness of the advocate who has undertaken this great cause-when these reflections press upon my mind, it is impossible for me not to feel both terrified and concerned at my own inadequacy to such a task. But when I reflect, however, on the encouragement which I have had, through the whole course of a long and laborious examination of this question, and how much candour I have experienced, and how conviction has increased within my own mind, in proportion as I have advanced in my labours;-when I reflect, especially, that however averse any gentleman may now be, yet we shall all be of one opinion in the end;-when I turn myself to these thoughts, I take courage-I determine to forget all my other fears, and I march forward with a firmer step in the full assurance that my cause will bear me out, and that I shall be able to justify my decision to release FuseSoC 1.4.

William Wilberforce, a man who apparently had a thing for extremely long sentences, might have said something a bit similar about the end of slavery, but that's not the topic for today. Today's topic is the new FuseSoC release. We now live in a world of git snapshots (and less slavery than 1789), and I don't expect an increase in the number after the decimal point in the configure script matter to most people. Still, I think it's nice to do a stable release once in a while. It helps packagers (where are you by the way? I'm still waiting for someone to make a FuseSoC rpm or deb), and more importantly, I can take this as an opportunity to break things. This will be the first version where a part of CAPI1 gets deprecated. There are some other noteworthy changes since FuseSoC 1.3, and although I have summarized the changes in the NEWS file, and I recently wrote a post about the new IP-Xact support there are other changes that could be worth explaining in further detail. I do realize that this would not be needed if someone had written proper documentation (where are you by the way? I'm still waiting for someone to write the documentation for me), but no one has, so this will have to do for now.

Prominent features

 

 File sets

Up until now, source code has been mainly verilog, with some support for C(++) for Verilator testbenches and VPI modules, together with a very limited support for VHDL in the Quartus backend flow. This part has been completely overhauled in this release, where filesets are introduced. Filesets is modeled on the IP-Xact filesets, and these will have a stronger connection in the future, as IP-Xact support is also introduced in this version. The verilog section will be deprecated at some point, so I suggest moving to filesets already. Here's a quick example on how to make the switch. The verilog section of the de0 nano system...

[verilog]
src_files =
 rtl/verilog/clkgen.v
 rtl/verilog/orpsoc_top.v
 backend/rtl/verilog/pll.v
 rtl/verilog/wb_intercon.v
 rtl/verilog/wb_intercon_dbg.v

tb_private_src_files =
 bench/orpsoc_tb.v
 bench/uart_decoder.v
include_files =
 rtl/verilog/include/or1200_defines.v
 rtl/verilog/include/orpsoc-defines.v
 rtl/verilog/wb_intercon.vh
 rtl/verilog/wb_intercon_dbg.vh
 sw/clear_r3_and_jump_to_0x100.vh
 sw/spi_uimage_loader.vh

tb_include_files =
 bench/spi_image.vh
 bench/test-defines.v

...becomes...

[fileset rtl_files]
files =
 rtl/verilog/clkgen.v
 rtl/verilog/orpsoc_top.v
 backend/rtl/verilog/pll.v
 rtl/verilog/wb_intercon.v
 rtl/verilog/wb_intercon_dbg.v
file_type = verilogSource
usage = sim synth

[fileset tb_files]
files =
 bench/orpsoc_tb.v
 bench/uart_decoder.v
file_type = verilogSource
usage = sim

[fileset include_files]
files =
 rtl/verilog/include/or1200_defines.v
 rtl/verilog/include/orpsoc-defines.v
 rtl/verilog/wb_intercon.vh
 rtl/verilog/wb_intercon_dbg.vh
 sw/clear_r3_and_jump_to_0x100.vh
 sw/spi_uimage_loader.vh
file_type = verilogSource
is_include_file = true
usage = sim synth

[fileset tb_include_files]
files =
 bench/spi_image.vh
 bench/test-defines.v
file_type = verilogSource
is_include_file = true
usage = sim

It's a few more lines, but the added flexibility outweighs the few extra bytes of ascii characters. It's now possible to set other file types, such as vhdlSource, or request specific language versions such as verilogSource-2001. The available file types are enumerated in the IP-Xact standard with some addtional ones allowed by FuseSoC (verilogSource-2005 and vhdlSource-2008 for now). The name of a fileset is not important, but the filesets are parsed in the order they appear in the .core file, so make sure that they are correctly ordered when dealing with languages where this is important.

The usage tag can be set to one or more items, and determines which tools that will use the fileset. These can be either a category (sim, synth) or a specific tool (verilator, quartus, modelsim...)

For languages that has a concept of libraries (VHDL, not verilog), the logical_name tag can be used to indicate library affiliation.


Another new feature is per-file attributes, which can be used to override the default value for the fileset. These attributes are placed inside square brackets at the end of the file. They are comma-separated and are either of the form attribute=value, or just attribute, to set boolean attributes. With per-file attributes, the above example can be changed to:

[fileset rtl_files]
files =
 rtl/verilog/clkgen.v
 rtl/verilog/orpsoc_top.v
 backend/rtl/verilog/pll.v
 rtl/verilog/wb_intercon.v
 rtl/verilog/wb_intercon_dbg.v
 rtl/verilog/include/or1200_defines.v[is_include_file]
 rtl/verilog/include/orpsoc-defines.v[is_include_file]
 rtl/verilog/wb_intercon.vh[is_include_file]
 rtl/verilog/wb_intercon_dbg.vh[is_include_file]
 sw/clear_r3_and_jump_to_0x100.vh[is_include_file]
 sw/spi_uimage_loader.vh[is_include_file]
file_type = verilogSource
usage = sim synth

[fileset tb_files]
files =
 bench/orpsoc_tb.v
 bench/uart_decoder.v
 bench/spi_image.vh[is_include_file,file_type=verilogSource-2005]
 bench/test-defines.v[is_include_file]
file_type = verilogSource
usage = sim

Note that the file_type attribute for spi_image.vh was only added to show how multiple attributes can be set.

If there is an IP-Xact component file for the core, FuseSoC can parse that for the filesets instead. In that case, the above example will look like this

[main]
component =
 de0_nano.xml

Yep, that's right. We can leave it all to IP-Xact. Except for when we need file types that aren't in the IP-Xact standard (again Verilog 2005 and VHDL 2008 are the primary cases here), and the usage will default to both sim and synth. Future versions of FuseSoC will allow overriding options in the IP-Xact files to handle these cases. The IP-Xact support is described in greater detail in an earlier post

Mixed-language support

With the new file set features in place, most of the simulators and synthesis tools now accept both verilog, systemVerilog and VHDL files simultaneously for mixed-language projects.

 

Compile-time parameter enhancements

Both build backends now support setting top-level verilog parameters at synthesis-time. This can be used for example to initialize a boot ROM with different contents, or setting a version tag at compile-time. Using the de0 nano example once again, the following can be added to the .core file to register a parameter

[parameter bootrom_file]
datatype    = file
description = Boot ROM contents in Verilog hex format
paramtype   = vlogparam
scope       = public

To select a different boot ROM, run fusesoc build de0_nano --bootrom_file=/path/to/bootrom.vh

Slightly related are some enhancements to the simulator backends. Both verilator and XSIM now accepts parameters which are turned into plusargs, and all simulator backends now analyse the CLI arguments before building the simulator model to save some time.

Distutils and pypi

Apparently all the cool kids put their Python code on pypi, and it was suggested that I should do the same with FuseSoC. The easy way to do that is to replace autotools with a Python-based build system called distutils...or setuptools... which at some point gets used by pip... to create an egg or a wheel... which can be installed with pip.... or easy_install. I'm really not sure. Python packaging is a complete mess with around ten competing build systems. Try to Google it if you don't believe me. It's insane. I think this tweet pretty much sums it up.

So what are the benefits of this new Python-based build system. A small reduction in line count of the configuration files and the possibility to upload to pypi. It doesn't handle dependencies unfortunately, and there is no way to uninstall a package. How I love progress! The autotools-based build system is still there, until I figure out what to do.

That's all for now. I have already plenty of things lined up for the FuseSoC 1.5 release

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