FuseSoC 1.12

It's February 25th 2021 today and you all know what that means! It's time for another FuseSoC release! So what happened since last time? Well, let's find out.

 

 First of all, as I mentioned in the 2020 retrospective, most of the work during this development cycle has been done by Philipp Wagner. Thanks Philipp! He wasn't the alone though. This release had in total 11 people contributing code and looking at the history this is the most people contributing on a single release ever. As always, I'm really happy to see the project grow, so thanks everyone for helping out.

This release should perhaps also be seen as a bit of calm before the storm. Practically no user-facing feature additions were made to the code, but a lot of things were done to make sure FuseSoC is in good shape for upcoming changes and to provide users with a more polished FuseSoC experience.

Testing

There was much focus on improving the testing on FuseSoC this cycle. Tests are vital to make sure that things don't break when the code is changed and that existing code really does what it is supposed to do. tox is now the preferred method for launching tests and has the benefit of being run in an isolated environment and therefore not requiring FuseSoC to be installed, or accidentally run the tests on another system-installed version of FuseSoC. The latter has actually caused a lot of headaches when you could sometimes make changes that were expected to make the tests fail but they still passed because they were not run against the version you had changed. But that's all in the past now thanks to tox. The tests also cover more functionality, mostly things that were discovered to be broken because there had previously been no test to detect when they broke. Related to testing FuseSoC, switched to using GitHub for CI instead of Travis and Appveyor

Cleanup

This cycle also contained a lot of my favorite pastime - removing things. Code is a cost, not an asset, and removing things makes it easier to focus on improvements. Cleaning up can be done at almost all time, but recent changes such as dropping Python 2 support, and perhaps more importantly a fresh pair of eyes, resulted in a lot of cleaning up this time. A lot of this was done internally, but also on the user-facing side there were some changes. Up until now there has been potential for mischief by specifying paths in the core files pointing to files outside of the core root. This was never meant to work and users trying this now get a proper scolding.

Two commands were marked as deprecated, pgm and init. For the former, the equivalent functionality can be accomplished by using the run command instead with the --run switch (Yeah, I know. It's not the most obvious syntax). The latter, which is intended to get the standard FuseSoC core library, can be done with fusesoc library add fusesoc_cores https://github.com/fusesoc/fusesoc-cores instead.

Also deprecated were the (probably since long broken) logicore and coregen providers. Those were always intended as a stop-gap measure and their job is better handled by a generator, using the EDA tools tcl API to generate IP cores or add .xci files to your core file. The best alternative depends a bit on the situation.

The last thing to be deprecated is the CAPI1 core description format. FuseSoC will keep supporting CAPI1 cores until FuseSoC version 2.0.0 comes along at some point in the future but it is highly recommended to update already now. And thankfully a core conversion tool is now available. The FuseSoC migration guide goes into more detail on how to use that. And in parallel to this deprecation, all CAPI1 cores from the FuseSoC standard library have been converted to CAPI2.

And finally, the already deprecated build and sim commands were removed in this release. Those commands were written for a CAPI1 world which no longer exists other than in our memories. The run command has since long taken over.

To get your code base ready for FuseSoC 2.0 (which shouldn’t be too far away) we recommend that all users address all deprecation warnings as soon as possible. Deprecated features won’t go away in FuseSoC 1.x, but will be removed in FuseSoC 2.0.

 Documentation

We have good reasons to celebrate the 1.12 release of FuseSoC. One of the most prevalent problems has been fixed, that of unreadable or non-existent documentation. Philipp has done an amazing job in rewriting the documentation pretty much from scratch, dividing it into different sections targeted for users and developers as well as trimming down the readme file from its previous stream of consciousness into an elevator pitch for engineers. Also building the documentation should now be easier for those who wish to do so.

So are there really no new features whatsoever? Not really. As mentioned initially, we have been holding things off to make sure there's a solid base to start from when we unleash a flurry of exciting features.

Ok, I snuck in a small feature, which turned out to be pretty much my only contribution this cycle. It is now possible to set parameters for generators directly in the targets. What does this mean? It's probably easiest to show with a small example. Imagine two targets, each using a generator to, say, select the number of really small CPUs to be instantiated in the design. This is configured by setting the count parameter in the generator to the value appropriate for each target.

targets:
  target1:
    generate: 
    - morecoregen1
  target2:
    generate: 
    - morecoregen2

generate:
  morecoregen1:
    generator: morecores
    parameters:
      count : 11
  morecoregen2:
    generator: morecores
    parameters:
      count : 73 

Maybe it's just me, but I think there's some obvious areas for improvement here, so from now on, you can do it like this instead.

targets:
  target1:
    generate: 
    - morecoregen: 
      count: 11
  target2:
    generate:
    - morecoregen:
      count : 73

generate:
  morecoregen:
    generator: morecores

Pretty nice, ain't it?