Happy sixth birthday FuseSoC

Today FuseSoC is turning six years old. That is probably something like 35 in software years. It has had a colourful past with some breakups and an identity crisis, but has now settled down and realized that it will not change the world in the same way that it used to think. It has spawned a few child projects which are not yet able to handle themselves in the world and still need their loving parent project. Being 35 also means that we can expect a FuseSoC middle-age crisis in a few years where it will try to reinvent itself in a desperate attempt to appear youthful. All in all, it's pretty similar to it's author.

As with most software, there is no birth certificate, but we will use the date of the first commit to the repo of what would become FuseSoC as the birth date. So what really happened on that fateful day that would become forever etched into history as the day when everything changed? According to Wikipedia, it wasn't a happy day overall, but none of those events are really related to FuseSoC.

As so often, we need to go back further in time and take a look at the events leading up to this day. It all started with the OpenRISC Reference Platform System on Chip version 2, or ORPSoCv2. This project was a combination of RTL code for the OpenRISC CPU together with a bunch of peripheral controller cores, drivers, example applications and miles of makefiles to build everything together into FPGA images that could be loaded onto a few select boards for running OpenRISC-based systems. Despite having one of the least sexy names ever, it was widely used by most people who dealt with OpenRISC and seems to still be in use by some people.  But it wasn't without flaws. Due to the tightly integrated nature of the project, everyone who wanted to add support for a new FPGA board or add some extra peripheral driver ended up with their own version of the project, each with their own bugs and features. Fixes were rarely submitted back upstream to the main ORPSoCv2 repo. Also, the RTL code for the CPU and peripheral controllers were copies of other repositories, which quickly started to diverge from their upstream counterparts. Again, none of that code was submitted upstream. There were also other issues with regards to scalability that started to show when more features were added. In short, it was time for something new.

I started sketching out what I would like to see in a successor, and then started implementing ORPSoCv3. Just like ORPSoCv2 this was a system of makefiles calling into other makefiles, but with a major difference. Instead of storing copies of cores, the upstream versions were fetched when they were requested in a SoC to avoid all the code duplication. After some time, I was ready to present my work in progress to the world. At that time I was working for the company that owned and maintained OpenCores. The git hype had already started to sweep through the software landscape and I had been trying to convince my co-workers that we needed to start making OpenCores support git instead of just SVN. I never managed to convince them, but at least I got them to set up a git server where I could put my project as a trial. Except for three or four outdated clones of other OpenRISC-related projects, I had the only git repo at the now defunct git.opencores.org. On August 30 20111 I made the first commit.

The better part of the coming year was spent on writing makefiles calling other makefile until one day I had enough and decided that I will never in my life write another makefile calling other makefiles. It was time to kill my darling. I started a new implementation in Python with the lessons learned and soon got to a state where I wanted to present it to the world. As I only had this one git repo and no real understanding of git work flows, my instinct was to clean out the old repo and just push the new code in. Unfortunately I never figured out how to get rid of the first commit, which resulted in this sequence of commits:

Even after the Python migration, FuseSoC (or ORPSoCv3 really) was still storing a lot of RTL code in the repo. It was a shaky relationship, and in August 2013 there was an inevitable separation of tool and RTL code. The RTL code went into a new project called orpsoc-cores. There wasn't any crying involved an both parties realized that it was best to go separate ways. A day later, the first released version, ORPSoC 3.0 was released.

Life went on, new features were added, bugs were fixed, ORPSoCv3 became older and fatter, but it became more and more evident that ORPSoC really didn't have anything to do with OpenRISC. Everything that was OpenRISC-specific had already moved to the orpsoc-cores repository and ORPSoCv3 was really a dependency manager and build system for any RTL code. It was once again time to cut some ties. As usual, names are harder than code, and I spent some time trying to figure out what to call the thing I had created. One of the main alternatives was SoCify, but it turned out someone else had already used that name. In hindsight, I'm really grateful for that. SoCify as it is a horrible name. The idea of FuseSoC came from the analogy of fusion reactions to build something bigger from a number of smaller cores. The minimalist in me also considered FuSoC, which is also pretty bad and sounds a bit like F*** you SoC. I do like FuseSoC though. In February 2014 the big rename was made, the project was moved to its current location and FuseSoC 1.0 was released.

Since then not much has happened. New features are added. Bugs are fixed, reintroduced and fixed again. FuseSoC is getting older and fatter. I'm really grateful for all help that I have received over the years. According to github, there have been 20 contributors to the code base, but there are also a number of other people who have submitted bugs or contributed to the RTL code in the standard core library. Big thanks to everyone involved.

Birthdays usually involve presents. But what can we give to a project that already has everything? How about a logo and a home page? That's the perfect gift for a six year old and on this big day I can proudly announce the brand new home page (Ssshhh...I have had the domain name since 2014, but don't tell FuseSoC) and the FuseSoC logo.

Happy birthday FuseSoC! I will now leave the word to the millions of users to tell their stories of how FuseSoC has changed their lives.

initial begin

Software is built up by layers and layers of abstractions, which has the pleasant effect of hiding all the underlying madness that computer software is built upon. If we still would be fearless enough to take the long and winding road down a user facing application, through the libraries, operating system and drivers, we would eventually end up at the register map. This is an impenetrable wall even for most of the hardcore close-to-the-metal low-level-driver gurus. This is the boundrary between the chips and the instructions that are meant to make the chips do something useful. This is however not the final frontier. Some fearless souls, calling themselves FPGA/ASIC designers, Digital Design Engineers or Hardware Developers have decided to take the spirit of Open Source and Free Software beyond the wall and into the realms of the silicon. In the Open Source world, hardware is generally considered Open Source friendly when there exists a documented register map and perhaps some use cases, so why do more? Well, for us on the hardware side, we want a little more than that. Hardware can be just as buggy as software, and working with closed-source IP cores are generally a pain. This ranges from the obvious problems that you can't debug your code properly to the insane license agreements and in many cases strange restrictions that the license holder can impose on the development environment. While these are all very practical reasons for doing all this, I think that the driving force for most of us is that it is pretty damn fun!

I, myself, come from a background of having worked professionally with FPGA and ASIC as a consultant for five years now, and been involved with software and hardware since my first stumbling peeks and pokes in QuickBasic in the mid-nineties. Over the years, I have enjoyed the great success of Open Source Software and contributed back to a bunch of different projects. In 2010, I got involved in the OpenRISC project, through my employer at that time. These last three years working on the OpenRISC project in my spare time, I have found myself in company of extremely talented people who are not afraid of learning new things or take on overwhelming challenges. Combined with a large ecosystem of IP cores, toolchains, operating systems, test suites, documentation, development tools and basically everything else you expect from a processor architecture, this has come to be a huge and very interesting project.

The main reason for starting this blog is to shed some light on all the things we are working in the digital domain of the Open Source ecosystem, and in particular the OpenRISC project. Searching around the internet, it turns out that the amount of written information is sparse. Apart from our ever-growing official OpenRISC page that holds our ever-growing wiki and links to most things related, Sven Andersson has written a series of articles about his experience with the OpenRISC as a newcomer to the scene. This has provided us with great feedback for how we can improve and streamline things, as well as getting many people interested in trying out this mythical CPU creature. Franck Jullien has also written some articles on his blog about his work with some cool debugging features for OpenRISC. Another resources that has served well over the years are a series of application notes from Embecosm on SystemC modelling, GDB protocol implementation and C libraries, written by long-time contributor Jeremy Bennett. Many of those articles has found use also outside of the OpenRISC world. There are probably many more articles that I have forgotten about, and it would be great if everyone who feel left out can come forward so that we can collect a definite list of all related articles. In addition to written articles, many of us like to show up at conferences to talk about what we do in the project, hang out and hack on things. Julius Baxter and I have held presentations (here and here) and a workshop at FSCONS and visited FOSDEM last year. 2012 was also the year that we held the first (hopefully annual) OpenRISC Conference, which was a great success. Sitting through the presentations, it was clear that the project is growing and that an impressive amount of work is being done by extremely talented hackers.

While all of these articles and presentations has given us a chance to show what we are doing, there are still a lot of really cool development that goes unnoticed for the unitiated. I hope to get some time to write about all the fun stuff that is going on, and most of all, write about all the fun stuff that I am doing.

Most of my own work isn't directly related to the OpenRISC CPU itself, but on the infrastructure that surrounds it. I'm maintaining an ethernet MAC, has started an extremely low-volume mailing list on the Wishbone bus (which is the bus that OpenRISC as well as a few other Open Source CPU:s use to connect to other IP cores), done some C library hacking, fixing bugs, reminding other people about forgotten patches and fixed bugs and been around to companies, conferences and schools to talk about using Open Source IP cores in their workflow. Since about two years my main focus has been on creating a platform for simulating individual cores as well as simulating and building systems based on the many fine IP cores that are available at OpenCores and other places. The project is called orpsocv3, or the OpenRISC Reference Platform System on Chip version 3, and is planned to replace our current platform orpsocv2. orpsocv3 is packed with functionality that will hopefully make development easier compared to the existing system, and will hopefully be prominently featured in coming articles. The code is still in an early development stage, but you can check it out here if you want to to see for yourself what all the cool kids are talking about. To avoid the infamous scope creep, I'm resisting the urge to write more about orpsocv3 now and instead conclude that proper introductions have been made and we can go on to the technical stuff for the next post.

end

Scope Creep

During my work on ORPSoCv3, I realized that there were some problems with the SPI Flash memory model that I planned to reuse from ORPSoCv2. To use the file (and more importantly to make it publicly available) it turned out I needed a written license agreement. I now had three choices:

1. Pretending like I didn't see the license - Not gonna happen. I'm building a product intended for both hobbyist and commercial use, so I want these things to be done correctly, or I will risk that they come back and haunt me.

2. Try to contact the right people to ask for a relicensed version of the file. It could be worth trying, as there is at least a company name and the author's name in the file header that I could use to track down the owner. On the other hand, the last update was in 2007 and even if I would find someone who could claim ownership, it's not very certain that they would allow relicensing the file.

3. Rewrite the code. Even though I have tried hard to not reinvent too many wheels in ORPSoCv3, this is sometimes the easiest way forward.


The third option, which is what I chose, has some added benefits too. The SPI flash model in ORPSoCv2 is targeted for a specific flash that we used on an old board that I don't intend to support in v3, so the new code could probably be made a bit more generic instead. Instead of a monolithic BFM for a chip, I could create a generic SPI BFM (which I'm sure would come in handy in other cases) and try out an idea I've been having about a memory that uses VPI callbacks to store data in dynamically created C structures instead.

This is where the scope creep started...

First of all, the idea of having a dynamically created memory instead of a huge twodimensional array comes from the assumption that in some cases, we need a large memory map, but we only read and write to the small parts of that memory. Having a huge static verilog array means we have to allocate a lot of memory that will never be used, and the simulator might need to check for events on every bit, which could slow things down considerably. (Note here that I'm using might and could, since I haven't done any benchmarks to prove anything yet. It could also be very simulator dependent). So the idea here is to make an array of pointers to memory segments and only malloc a page when it is written to for the first time. The verilog code would have $read and $write functions that can read from memory and some init functions to preload images (elf, exo, bin, vmem, srec and whatever could be useful).

I started hacking on the C code, and it seemed reasonably simple to do this. To try it out, I wanted some real world testing, but unfortunately I didn't have any nice SPI test cases (nor a SPI BFM). The VPI memory backend however would be a good match for a simple model of a Wishbone SDRAM controller . If I could replace the existing controller (Scope Creep), I would be able to run all the existing ORPSoCv2 test cases to get some verification. Looking at the code for the existing model, it turned out to be a little awkward to fit the $read and $write commands in to the existing Wishbone memory model, so I decided to find a proper Wishbone BFM that I could use to interface with the memory backend instead (Scope Creep).

Searching around the internet I found a few commercial ones, a nice looking one in System Verilog, a VHDL version and an implementation in the ethmac testbench (an IP that I also happen to be co-maintainer of).

None of the existing models were up to the task however as I need it to be pure verilog and support Wishbone B3 burst transactions. The first requirement is because neither Icarus Verilog or the free Altera-provided Modelsim supports mixed language simulation, and everything I have is in verilog at the moment. Only the BFM from ethmac fulfilled the first requirement, but unfortunately it didn't seem to support burst transactions. The only thing left to do is to write a brand new verilog based Wishbone slave BFM myself (Scope Creep). I figured that would come in handy anyway, so it wasn't that much of a problem.

Implementing a simple BFM wasn't too much work, but it turns out that having a three weeks old baby and a full-time employement makes it a bit harder to find spare time to work on side projects like this. It also took a while longer since I at some point decided to refactor some things in ORPSoCv3 (Scope Creep),  make a Wishbone interconnect generator to make it easier to hook up the memory model to a CPU (Score Creep), and to test the inteconnect I would need to build a Wishbone Master BFM too (Scope Creep). The interconnect part was eventually dropped, but I did implement a basic Wishbone Master BFM. I also decided to start with a static memory before I tried out the VPI backed memory model.

Having come this far I thought it would be fun to tell the world about my new BFM once it was done, show of the capabilities of ORPSoCv3 and provide some cool benchmarks, and since I'm about ten years behind the rest of the world, I decided it was now time to start my first blog (Major Scope Creep!). Starting a new blog leads to some big decisions. I would either need to use an available web service to host my blog or do it myself. I decided to host it on my NAS since there is already a Wordpress package available for it. After installing the package and fiddling with MySQL permissions (Scope Creep) I realized that I needed a name for the blog, so I took a few days to come up with a number of witty names (Scope Creep), and abandoning them one after one as it turns out that all witty names for a FPGA/Hardware/Open Source/electronics blogs are already taken (stupid internet!).

About this time I also realized that I didn't really want to host my own blog since it probably meant that I had to tighten up the security of my home network and think a bit about how to provide decent availability, so the focus shifted to finding a good platform to use instead. This left me again with several choices, and the only thing to do was to read up on all the pros and cons of available services (Scope Creep). I started registering an account on wordpress, but had to stop when I realized that I still didn't have a name for the blog.

By now I was starting to get really tired of my own inability to finalize things, so once I came up with a name for the blog, I registered a blogspot account instead and started writing. The basic functionality for the BFM is mostly finished now, but I to avoid further delays in putting this first post out, I'll finish it and push it to the ORPSoCv3 repo after I'm done writing. The slave seems to have identical timing to the model I'm replacing, so I'll consider that good enough for now.

I'm fully aware that this first post need a lot of background informaton to make sense for people outside of the inner-most circle in the OpenRISC project, and that I should have written introductions about myself, the OpenRISC project, ORPSoC, Wishbone, BFM:s Open Source Hardware and whatever else I've benn talking about. Well, to relate to the title, I had to stop this scope creep before I totally lost control. So to finish things up and provide pointers about what I might write about in the coming articles, here's a summary of the work that led up to this article.

Initial target: Add an SPI memory model to ORPSoCv3
Work started: VPI backend for a dynamic memory model, Test bench for Wishbone interconnect, BFM-based static memory model
Work done: Basic Wishbone Master/Slave BFM, Choose a blog platform, Write a first post
Work planned: SPI master/slave BFM, Wishbone Interconnect Generator, Finalize, document and release Wishbone BFM, continue working on rough edges in ORPSoCv3
Work dropped: Hosting a blog, secure the home network, integrate existing Wishbone BFM

As you can see, I'm nowhere near starting on the SPI flash memory model, but at least I have a blog and a partially working Wishbone BFM! :)